@simplysm/excel 14.0.47 → 14.0.49

package/README.md

@@ -0,0 +1,149 @@
+# @simplysm/excel
+
+Excel 워크북(xlsx) 읽기/쓰기 라이브러리. DOM 의존성이 없어 Node.js와 브라우저 양쪽에서 동작하는 neutral 패키지다. Lazy Loading 아키텍처로 대용량 파일도 메모리 효율적으로 처리한다.
+
+## Installation
+
+```bash
+npm install @simplysm/excel
+```
+
+## API Overview
+
+### Core Classes
+
+| API | Type | Description |
+|-----|------|-------------|
+| `ExcelWorkbook` | class | Excel 워크북 진입점. 워크시트 생성/조회, 바이트 내보내기, ZIP 리소스 관리 |
+| `ExcelWorksheet` | class | 워크시트. 셀/행/열 접근, 행/셀 복사, 데이터 테이블 읽기, 이미지 삽입, 시트명 변경 |
+| `ExcelCell` | class | 개별 셀. 값/수식 읽기/쓰기, 스타일 설정, 셀 병합 |
+| `ExcelRow` | class | 워크시트 행. 셀 접근, 행 전체 셀 조회 |
+| `ExcelCol` | class | 워크시트 열. 셀 접근, 열 너비 설정 |
+
+→ See [docs/core-classes.md](./docs/core-classes.md) for details.
+
+### Wrapper
+
+| API | Type | Description |
+|-----|------|-------------|
+| `ExcelWrapper` | class | Zod 스키마 기반 타입 안전한 Excel 읽기/쓰기. 헤더 자동 생성, 유효성 검사, 필수 필드 강조 |
+
+→ See [docs/wrapper.md](./docs/wrapper.md) for details.
+
+### Utilities
+
+| API | Type | Description |
+|-----|------|-------------|
+| `ExcelUtils` | class | 셀 주소 변환 (좌표↔문자열), 날짜↔숫자 변환, 숫자 형식 매핑 (정적 메서드) |
+
+→ See [docs/utilities.md](./docs/utilities.md) for details.
+
+### Types
+
+| API | Type | Description |
+|-----|------|-------------|
+| `ExcelValueType` | type | 셀 값 타입: number, string, DateOnly, DateTime, Time, boolean, undefined |
+| `ExcelNumberFormat` | type | 숫자 형식 이름: "number", "string", "DateOnly", "DateTime", "Time" |
+| `ExcelCellType` | type | 셀 타입: "s"(공유문자열), "b"(boolean), "str"(수식문자열), "n"(숫자), "inlineStr", "e"(에러) |
+| `ExcelAddressPoint` | interface | 셀 좌표 (0 기반 r, c) |
+| `ExcelAddressRangePoint` | interface | 셀 범위 좌표 (시작점 s, 끝점 e) |
+| `ExcelStyleOptions` | interface | 셀 스타일 옵션 (배경색, 테두리, 정렬, 숫자 형식) |
+| `ExcelBorderPosition` | type | 테두리 위치: "left", "right", "top", "bottom" |
+| `ExcelHorizontalAlign` | type | 가로 정렬: "left", "center", "right" |
+| `ExcelVerticalAlign` | type | 세로 정렬: "top", "center", "bottom" |
+| `ExcelXml` | interface | XML 처리 클래스가 구현하는 인터페이스 (내부용) |
+| `ExcelXmlContentTypeData` | interface | `[Content_Types].xml` 데이터 구조 (내부용) |
+| `ExcelXmlRelationshipData` | interface | `*.rels` 파일 데이터 구조 (내부용) |
+| `ExcelRelationshipData` | interface | 개별 Relationship 엔트리 데이터 (내부용) |
+| `ExcelXmlWorkbookData` | interface | `workbook.xml` 데이터 구조 (내부용) |
+| `ExcelXmlWorksheetData` | interface | `worksheet*.xml` 데이터 구조 (내부용) |
+| `ExcelRowData` | interface | 행 XML 데이터 (내부용) |
+| `ExcelCellData` | interface | 셀 XML 데이터 (내부용) |
+| `ExcelXmlDrawingData` | interface | `drawing*.xml` 데이터 구조 (내부용) |
+| `ExcelXmlSharedStringData` | interface | `sharedStrings.xml` 데이터 구조 (내부용) |
+| `ExcelXmlSharedStringDataSi` | type | SharedString 개별 항목 (단순 텍스트 or rich text) |
+| `ExcelXmlSharedStringDataText` | type | SharedString 텍스트 데이터 (내부용) |
+| `ExcelXmlStyleData` | interface | `styles.xml` 데이터 구조 (내부용) |
+| `ExcelXmlStyleDataXf` | interface | 셀 서식(xf) 데이터 (내부용) |
+| `ExcelXmlStyleDataFill` | interface | 채우기 스타일 데이터 (내부용) |
+| `ExcelXmlStyleDataBorder` | interface | 테두리 스타일 데이터 (내부용) |
+
+→ See [docs/types.md](./docs/types.md) for details.
+
+## Usage Examples
+
+### 새 Excel 파일 생성 및 저장
+
+```typescript
+import { ExcelWorkbook } from "@simplysm/excel";
+
+const wb = new ExcelWorkbook();
+try {
+  const ws = await wb.addWorksheet("Sheet1");
+  
+  // 헤더 행
+  await ws.cell(0, 0).setValue("이름");
+  await ws.cell(0, 1).setValue("나이");
+  
+  // 데이터 행
+  await ws.cell(1, 0).setValue("김철수");
+  await ws.cell(1, 1).setValue(30);
+  
+  const bytes = await wb.toBytes();
+  // 파일 저장 또는 전송
+} finally {
+  await wb.close();
+}
+```
+
+### 기존 Excel 파일 읽기
+
+```typescript
+import { ExcelWorkbook } from "@simplysm/excel";
+
+const bytes = /* 파일 바이트 배열 */;
+const wb = new ExcelWorkbook(bytes);
+try {
+  // 시트명 또는 인덱스(0 기반)로 조회
+  const ws = await wb.getWorksheet(0);
+  
+  // 개별 셀 읽기
+  const value = await ws.cell(0, 0).getValue();
+  
+  // 전체 데이터 테이블 읽기 (첫 행이 헤더)
+  const table = await ws.getDataTable();
+} finally {
+  await wb.close();
+}
+```
+
+### Zod 스키마 기반 타입 안전한 작업
+
+```typescript
+import { ExcelWrapper } from "@simplysm/excel";
+import { z } from "zod";
+
+const schema = z.object({
+  name: z.string().describe("이름"),
+  age: z.number().describe("나이"),
+  email: z.string().optional().describe("이메일"),
+});
+
+const wrapper = new ExcelWrapper(schema);
+
+// 레코드 배열을 Excel로 쓰기
+const records = [
+  { name: "김철수", age: 30, email: "kim@example.com" },
+  { name: "이영희", age: 28 },
+];
+const wb = await wrapper.write("사람", records);
+try {
+  const bytes = await wb.toBytes();
+} finally {
+  await wb.close();
+}
+
+// Excel 파일을 레코드 배열로 읽기 (유효성 검사 포함)
+const bytes = /* 파일 바이트 배열 */;
+const data = await wrapper.read(bytes, "사람");
+```

package/dist/xml/excel-xml-workbook.js

@@ -96,8 +96,8 @@ export class ExcelXmlWorkbook {
         return (this.data.workbook.sheets?.[0].sheet ?? []).single((item) => num.parseInt(item.$["r:id"]) === id);
     }
     _getReplacedName(name) {
-        //-- 잘못된 시트 이름 문자를 "_"로 대체
-        return name.replace(/[:\\/?*\[\]']/g, "_");
+        //-- 잘못된 시트 이름 문자 제거. 전부 제거되어 빈 문자열이 되면 "Sheet" 사용.
+        return name.replace(/[:\\/?*\[\]']/g, "") || "Sheet";
     }
 }
 //# sourceMappingURL=excel-xml-workbook.js.map

package/dist/xml/excel-xml-workbook.js.map

@@ -1 +1 @@
-{"version":3,"file":"excel-xml-workbook.js","sourceRoot":"","sources":["../../src/xml/excel-xml-workbook.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"excel-xml-workbook.js","sourceRoot":"","sources":["../../src/xml/excel-xml-workbook.ts"],"names":[],"mappings":"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"}

package/docs/core-classes.md

@@ -0,0 +1,453 @@
+# Core Classes
+
+## `ExcelWorkbook`
+
+Excel 워크북 처리 클래스. 내부적으로 ZIP 리소스를 관리하므로 사용 후 반드시 `try-finally` 블록에서 `close()`를 호출해야 한다.
+
+```typescript
+export class ExcelWorkbook {
+  readonly zipCache: ZipCache;
+
+  constructor(arg?: Blob | Bytes);
+
+  async getWorksheetNames(): Promise<string[]>;
+  async addWorksheet(name: string): Promise<ExcelWorksheet>;
+  async getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet>;
+  async toBytes(): Promise<Bytes>;
+  async toBlob(): Promise<Blob>;
+  async close(): Promise<void>;
+}
+```
+
+### Constructor
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `arg` | `Blob \| Bytes \| undefined` | 기존 Excel 파일 데이터. 생략하면 새 워크북을 생성한다 |
+
+### Methods
+
+#### `getWorksheetNames()`
+
+워크북의 모든 워크시트 이름을 배열로 반환한다.
+
+#### `addWorksheet(name)`
+
+새 워크시트를 생성하여 `ExcelWorksheet` 인스턴스를 반환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | 워크시트 이름 |
+
+#### `getWorksheet(nameOrIndex)`
+
+이름 또는 0 기반 인덱스로 워크시트를 조회하여 반환한다. 찾을 수 없으면 에러를 던진다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `nameOrIndex` | `string \| number` | 워크시트 이름 또는 0 기반 인덱스 |
+
+#### `toBytes()`
+
+워크북을 `Bytes`(Uint8Array)로 내보낸다.
+
+#### `toBlob()`
+
+워크북을 `Blob`으로 내보낸다. MIME 타입은 `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`이다.
+
+#### `close()`
+
+ZIP 리더와 내부 캐시를 정리한다. 이미 닫힌 워크북에 대해 호출해도 안전하다 (no-op). 닫힌 워크북의 메서드를 호출하면 에러가 발생한다.
+
+---
+
+## `ExcelWorksheet`
+
+Excel 워크시트를 나타내는 클래스. 셀 접근, 행/열 복사, 데이터 테이블 처리, 이미지 삽입, 뷰 설정 기능을 제공한다.
+
+```typescript
+export class ExcelWorksheet {
+  constructor(zipCache: ZipCache, relId: number, targetFileName: string);
+
+  // Name
+  async getName(): Promise<string>;
+  async setName(newName: string): Promise<void>;
+
+  // Cell Access (0 기반)
+  row(r: number): ExcelRow;
+  cell(r: number, c: number): ExcelCell;
+  col(c: number): ExcelCol;
+
+  // Copy
+  async copyRowStyle(srcR: number, targetR: number): Promise<void>;
+  async copyCellStyle(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>;
+  async copyRow(srcR: number, targetR: number): Promise<void>;
+  async copyCell(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>;
+  async insertCopyRow(srcR: number, targetR: number): Promise<void>;
+
+  // Range
+  async getRange(): Promise<ExcelAddressRangePoint>;
+  async getCells(): Promise<ExcelCell[][]>;
+
+  // Data
+  async getDataTable(opt?: {
+    headerRowIndex?: number;
+    checkEndColIndex?: number;
+    usableHeaderNameFn?: (headerName: string) => boolean;
+  }): Promise<Record<string, ExcelValueType>[]>;
+  async setDataMatrix(matrix: ExcelValueType[][]): Promise<void>;
+  async setRecords(records: Record<string, ExcelValueType>[]): Promise<void>;
+
+  // View
+  async setZoom(percent: number): Promise<void>;
+  async freezeAt(point: { r?: number; c?: number }): Promise<void>;
+
+  // Image
+  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>;
+}
+```
+
+### Name Methods
+
+#### `getName()`
+
+워크시트 이름을 반환한다.
+
+#### `setName(newName)`
+
+워크시트 이름을 변경한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `newName` | `string` | 새 워크시트 이름 |
+
+### Cell Access Methods
+
+모든 좌표는 0 기반 인덱스이다.
+
+#### `row(r)`
+
+행 객체를 반환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `r` | `number` | 행 인덱스 (0 기반) |
+
+#### `cell(r, c)`
+
+셀 객체를 반환한다. 동일 좌표에 대해 항상 동일한 `ExcelCell` 인스턴스를 반환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `r` | `number` | 행 인덱스 (0 기반) |
+| `c` | `number` | 열 인덱스 (0 기반) |
+
+#### `col(c)`
+
+열 객체를 반환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `c` | `number` | 열 인덱스 (0 기반) |
+
+### Copy Methods
+
+#### `copyRowStyle(srcR, targetR)`
+
+원본 행의 스타일을 대상 행으로 복사한다. 데이터 범위 내의 모든 열에 대해 셀 스타일을 복사한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `srcR` | `number` | 원본 행 인덱스 (0 기반) |
+| `targetR` | `number` | 대상 행 인덱스 (0 기반) |
+
+#### `copyCellStyle(srcAddr, targetAddr)`
+
+원본 셀의 스타일을 대상 셀로 복사한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `srcAddr` | `ExcelAddressPoint` | 원본 셀 좌표 |
+| `targetAddr` | `ExcelAddressPoint` | 대상 셀 좌표 |
+
+#### `copyRow(srcR, targetR)`
+
+원본 행을 대상 행으로 복사한다 (덮어쓰기).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `srcR` | `number` | 원본 행 인덱스 (0 기반) |
+| `targetR` | `number` | 대상 행 인덱스 (0 기반) |
+
+#### `copyCell(srcAddr, targetAddr)`
+
+원본 셀을 대상 셀로 복사한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `srcAddr` | `ExcelAddressPoint` | 원본 셀 좌표 |
+| `targetAddr` | `ExcelAddressPoint` | 대상 셀 좌표 |
+
+#### `insertCopyRow(srcR, targetR)`
+
+원본 행을 대상 위치에 삽입 복사한다. 대상 위치 이하의 기존 행은 한 칸 아래로 밀린다. 병합 셀도 자동으로 이동/확장된다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `srcR` | `number` | 복사할 원본 행 인덱스 (0 기반) |
+| `targetR` | `number` | 삽입할 대상 행 인덱스 (0 기반) |
+
+**병합 셀 처리:**
+- 삽입 지점을 관통하는 다중행 병합은 자동으로 1행 확장됨
+- 원본 행의 단일행 병합만 대상 행에 복사됨
+
+### Range Methods
+
+#### `getRange()`
+
+워크시트의 데이터 범위를 `ExcelAddressRangePoint`로 반환한다.
+
+#### `getCells()`
+
+모든 셀을 2차원 배열(`ExcelCell[][]`)로 반환한다.
+
+### Data Methods
+
+#### `getDataTable(opt?)`
+
+워크시트 데이터를 테이블(레코드 배열)로 반환한다. 지정된 헤더 행(기본값: 첫 번째 행)을 기준으로 이하의 데이터를 읽는다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `opt.headerRowIndex` | `number \| undefined` | 헤더 행 인덱스 (기본값: 데이터 범위의 시작 행) |
+| `opt.checkEndColIndex` | `number \| undefined` | 데이터 끝을 판단할 열 인덱스. 이 열이 비어있는 행을 만나면 데이터가 끝난 것으로 판단한다 |
+| `opt.usableHeaderNameFn` | `(headerName: string) => boolean \| undefined` | 사용 가능한 헤더를 필터링하는 함수. 반환값이 `false`인 헤더는 제외된다 |
+
+**반환값:** `Record<string, ExcelValueType>[]` - 헤더를 키로 하는 레코드 배열
+
+#### `setDataMatrix(matrix)`
+
+2차원 배열 데이터를 워크시트에 쓴다. (0, 0) 위치부터 시작하여 데이터를 기록한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `matrix` | `ExcelValueType[][]` | 2차원 배열 데이터 (행 우선, `matrix[0]`이 첫 번째 행) |
+
+#### `setRecords(records)`
+
+레코드 배열을 워크시트에 쓴다. 첫 번째 행(r=0)에 헤더가 자동 생성되고, 이후 행(r=1...)에 데이터가 기록된다. 모든 레코드의 필드를 수집하여 헤더로 사용한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `records` | `Record<string, ExcelValueType>[]` | 레코드 배열 |
+
+### View Methods
+
+#### `setZoom(percent)`
+
+워크시트 확대/축소 비율을 설정한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `percent` | `number` | 확대/축소 퍼센트 |
+
+#### `freezeAt(point)`
+
+행/열 틀 고정을 설정한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `point.r` | `number \| undefined` | 고정할 행 인덱스 (0 기반) |
+| `point.c` | `number \| undefined` | 고정할 열 인덱스 (0 기반) |
+
+### Image Methods
+
+#### `addImage(opts)`
+
+워크시트에 이미지를 삽입한다. 같은 시트의 첫 이미지 호출 시 `drawing1.xml` 생성, 이후 이미지는 동일 drawing에 추가된다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `opts.bytes` | `Bytes` | 이미지 바이너리 데이터 |
+| `opts.ext` | `string` | 이미지 확장자 (예: `"png"`, `"jpg"`, `"gif"`) |
+| `opts.from` | `{ r: number; c: number; rOff?: number \| string; cOff?: number \| string }` | 이미지 시작 위치. `r`/`c`는 0 기반 행/열 인덱스, `rOff`/`cOff`는 선택적 EMU 오프셋 |
+| `opts.to` | `{ r: number; c: number; rOff?: number \| string; cOff?: number \| string } \| undefined` | 이미지 끝 위치. 생략 시 기본값은 `{ r: from.r + 1, c: from.c + 1 }`이다 |
+
+**이미지 파일 관리:**
+- 이미지는 `xl/media/image1.ext`, `xl/media/image2.ext` 등으로 자동 관리됨
+- 기존 파일명과 중복되지 않도록 인덱스 자동 증가
+
+---
+
+## `ExcelCell`
+
+Excel 셀을 나타내는 클래스. 값 읽기/쓰기, 수식, 스타일, 셀 병합 기능을 제공한다. 모든 메서드가 `async`인 이유는 셀 타입에 따라 필요한 XML만 선택적으로 로드하는 Lazy Loading 아키텍처 때문이다.
+
+```typescript
+export class ExcelCell {
+  readonly addr: ExcelAddressPoint;
+
+  constructor(zipCache: ZipCache, targetFileName: string, r: number, c: number);
+
+  // Value
+  async setValue(val: ExcelValueType): Promise<void>;
+  async getValue(): Promise<ExcelValueType>;
+  async setFormula(val: string | undefined): Promise<void>;
+  async getFormula(): Promise<string | undefined>;
+
+  // Merge
+  async merge(r: number, c: number): Promise<void>;
+
+  // Style
+  async getStyleId(): Promise<string | undefined>;
+  async setStyleId(styleId: string | undefined): Promise<void>;
+  async setStyle(opts: ExcelStyleOptions): Promise<void>;
+}
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `addr` | `ExcelAddressPoint` | 셀 주소 (0 기반 행/열 인덱스) |
+
+### Value Methods
+
+#### `setValue(val)`
+
+셀 값을 설정한다. `undefined`를 전달하면 셀이 삭제된다. `DateOnly`, `DateTime`, `Time` 인스턴스를 전달하면 내부적으로 Excel 날짜 숫자로 변환하고 적절한 numFmt를 설정한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `val` | `ExcelValueType` | 셀 값 (`number \| string \| DateOnly \| DateTime \| Time \| boolean \| undefined`) |
+
+#### `getValue()`
+
+셀 값을 반환한다. 셀 타입과 스타일에 따라 적절한 JavaScript 타입으로 변환한다. 비어있는 셀은 `undefined`를 반환한다.
+
+#### `setFormula(val)`
+
+셀에 수식을 설정한다. `undefined`를 전달하면 수식이 제거된다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `val` | `string \| undefined` | 수식 문자열 (예: `"SUM(A1:A10)"`) |
+
+#### `getFormula()`
+
+셀 수식을 반환한다. 수식이 없으면 `undefined`를 반환한다.
+
+### Merge Methods
+
+#### `merge(r, c)`
+
+현재 셀에서 지정된 끝 좌표까지 셀을 병합한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `r` | `number` | 병합 끝 행 인덱스 (0 기반) |
+| `c` | `number` | 병합 끝 열 인덱스 (0 기반) |
+
+### Style Methods
+
+#### `getStyleId()`
+
+셀의 스타일 ID를 반환한다. 스타일이 없으면 `undefined`를 반환한다.
+
+#### `setStyleId(styleId)`
+
+셀의 스타일 ID를 직접 설정한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `styleId` | `string \| undefined` | 스타일 ID |
+
+#### `setStyle(opts)`
+
+셀 스타일을 설정한다. 기존 스타일이 있으면 클론 후 병합한다.
+
+커스텀 Excel formatCode를 지정하려면 `numberFormatCode`를 사용한다:
+
+```typescript
+await cell.setStyle({ numberFormatCode: "0.000000" });  // 소수점 6자리
+await cell.setStyle({ numberFormatCode: "#,##0.00" });   // 천 단위 구분 + 2자리
+await cell.setStyle({ numberFormatCode: "0.00%" });      // 퍼센트
+```
+
+`numberFormat`(프리셋)과 `numberFormatCode`(커스텀)가 동시에 지정되면 `numberFormatCode`가 우선 적용된다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `opts` | `ExcelStyleOptions` | 스타일 옵션 (배경색, 테두리, 정렬, 숫자 형식) |
+
+---
+
+## `ExcelRow`
+
+Excel 워크시트의 행을 나타내는 클래스. 셀 접근 기능을 제공한다.
+
+```typescript
+export class ExcelRow {
+  constructor(zipCache: ZipCache, targetFileName: string, r: number, cellFactory: (c: number) => ExcelCell);
+
+  cell(c: number): ExcelCell;
+  async getCells(): Promise<ExcelCell[]>;
+}
+```
+
+### Methods
+
+#### `cell(c)`
+
+지정된 열 인덱스의 셀을 반환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `c` | `number` | 열 인덱스 (0 기반) |
+
+#### `getCells()`
+
+행의 모든 셀을 배열로 반환한다. 데이터 범위 내의 모든 열에 대한 셀이 포함된다.
+
+---
+
+## `ExcelCol`
+
+Excel 워크시트의 열을 나타내는 클래스. 셀 접근 및 열 너비 설정 기능을 제공한다.
+
+```typescript
+export class ExcelCol {
+  constructor(zipCache: ZipCache, targetFileName: string, c: number, cellFactory: (r: number) => ExcelCell);
+
+  cell(r: number): ExcelCell;
+  async getCells(): Promise<ExcelCell[]>;
+  async setWidth(size: number): Promise<void>;
+}
+```
+
+### Methods
+
+#### `cell(r)`
+
+지정된 행 인덱스의 셀을 반환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `r` | `number` | 행 인덱스 (0 기반) |
+
+#### `getCells()`
+
+열의 모든 셀을 배열로 반환한다. 데이터 범위 내의 모든 행에 대한 셀이 포함된다.
+
+#### `setWidth(size)`
+
+열 너비를 설정한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `size` | `number` | 열 너비 |

package/docs/types.md

@@ -0,0 +1,459 @@
+# Types
+
+## Value Types
+
+### `ExcelValueType`
+
+셀에 저장할 수 있는 값의 타입이다.
+
+```typescript
+export type ExcelValueType = number | string | DateOnly | DateTime | Time | boolean | undefined;
+```
+
+### `ExcelNumberFormat`
+
+숫자 형식 이름이다. `ExcelUtils`의 변환 메서드와 `ExcelStyleOptions.numberFormat`에서 사용한다.
+
+```typescript
+export type ExcelNumberFormat = "number" | "string" | "DateOnly" | "DateTime" | "Time";
+```
+
+### `ExcelCellType`
+
+Excel 셀 타입이다. XML의 `t` 속성에 대응한다.
+
+```typescript
+export type ExcelCellType = "s" | "b" | "str" | "n" | "inlineStr" | "e";
+```
+
+| Value | Description |
+|-------|-------------|
+| `"s"` | 공유 문자열 (SharedString) |
+| `"b"` | boolean |
+| `"str"` | 수식 결과 문자열 |
+| `"n"` | 숫자 |
+| `"inlineStr"` | 인라인 문자열 (서식 있는 텍스트) |
+| `"e"` | 에러 |
+
+## Address Types
+
+### `ExcelAddressPoint`
+
+셀 좌표를 나타내는 인터페이스이다. 모든 좌표는 0 기반이다.
+
+```typescript
+export interface ExcelAddressPoint {
+  r: number;
+  c: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `r` | `number` | 행 인덱스 (0 기반) |
+| `c` | `number` | 열 인덱스 (0 기반) |
+
+### `ExcelAddressRangePoint`
+
+셀 범위 좌표를 나타내는 인터페이스이다.
+
+```typescript
+export interface ExcelAddressRangePoint {
+  s: ExcelAddressPoint;
+  e: ExcelAddressPoint;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `s` | `ExcelAddressPoint` | 시작 좌표 |
+| `e` | `ExcelAddressPoint` | 끝 좌표 |
+
+## Style Types
+
+### `ExcelStyleOptions`
+
+셀 스타일 옵션 인터페이스이다.
+
+```typescript
+export interface ExcelStyleOptions {
+  background?: string;
+  border?: ExcelBorderPosition[];
+  horizontalAlign?: ExcelHorizontalAlign;
+  verticalAlign?: ExcelVerticalAlign;
+  numberFormat?: ExcelNumberFormat;
+  numberFormatCode?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `background` | `string \| undefined` | 배경색 (ARGB 형식, 8자리 16진수. 예: `"00FF0000"` = 빨강. alpha는 반전 값) |
+| `border` | `ExcelBorderPosition[] \| undefined` | 테두리 위치 배열 |
+| `horizontalAlign` | `ExcelHorizontalAlign \| undefined` | 가로 정렬 |
+| `verticalAlign` | `ExcelVerticalAlign \| undefined` | 세로 정렬 |
+| `numberFormat` | `ExcelNumberFormat \| undefined` | 숫자 형식 프리셋 |
+| `numberFormatCode` | `string \| undefined` | 커스텀 Excel formatCode 문자열 (예: `"0.000000"`, `"#,##0.00"`, `"0.00%"`) |
+
+**우선순위:** `numberFormatCode`가 지정되면 `numberFormat`보다 우선 적용된다. 동일한 formatCode는 `numFmts`에 중복 등록되지 않는다.
+
+### `ExcelBorderPosition`
+
+테두리 위치를 나타내는 타입이다.
+
+```typescript
+export type ExcelBorderPosition = "left" | "right" | "top" | "bottom";
+```
+
+### `ExcelHorizontalAlign`
+
+가로 정렬을 나타내는 타입이다.
+
+```typescript
+export type ExcelHorizontalAlign = "center" | "left" | "right";
+```
+
+### `ExcelVerticalAlign`
+
+세로 정렬을 나타내는 타입이다.
+
+```typescript
+export type ExcelVerticalAlign = "center" | "top" | "bottom";
+```
+
+## Excel XML Interface
+
+### `ExcelXml`
+
+XML 처리 클래스가 구현하는 인터페이스이다. 내부 구현에 사용되며, `xml/` 디렉터리의 클래스들이 이를 구현한다.
+
+```typescript
+export interface ExcelXml {
+  readonly data: unknown;
+  cleanup(): void;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `data` | `unknown` | XML 파싱된 데이터 |
+| `cleanup()` | `() => void` | `ZipCache.toBytes()` 직전에 호출되어 직렬화 전 데이터를 정리한다 |
+
+## XML Data Types
+
+아래 인터페이스들은 xlsx 내부 XML 파일의 데이터 구조를 타입으로 표현한 것이다. 주로 내부 구현에 사용된다.
+
+### `ExcelXmlContentTypeData`
+
+`[Content_Types].xml` 데이터 구조이다.
+
+```typescript
+export interface ExcelXmlContentTypeData {
+  Types: {
+    $: { xmlns: string };
+    Default: { $: { Extension: string; ContentType: string } }[];
+    Override: { $: { PartName: string; ContentType: string } }[];
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `Types.$` | `{ xmlns: string }` | 네임스페이스 |
+| `Types.Default` | `Array` | 확장자별 기본 콘텐트 타입 |
+| `Types.Default.$.Extension` | `string` | 파일 확장자 |
+| `Types.Default.$.ContentType` | `string` | MIME 타입 |
+| `Types.Override` | `Array` | 파일별 오버라이드 콘텐트 타입 |
+| `Types.Override.$.PartName` | `string` | 파일 경로 |
+| `Types.Override.$.ContentType` | `string` | MIME 타입 |
+
+### `ExcelXmlRelationshipData`
+
+`*.rels` 파일 데이터 구조이다.
+
+```typescript
+export interface ExcelXmlRelationshipData {
+  Relationships: {
+    $: { xmlns: string };
+    Relationship?: ExcelRelationshipData[];
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `Relationships.$` | `{ xmlns: string }` | 네임스페이스 |
+| `Relationships.Relationship` | `ExcelRelationshipData[] \| undefined` | 관계 항목 배열 |
+
+### `ExcelRelationshipData`
+
+개별 Relationship 엔트리 데이터이다.
+
+```typescript
+export interface ExcelRelationshipData {
+  $: {
+    Id: string;
+    Target: string;
+    Type: string;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `$.Id` | `string` | 관계 ID (예: `"rId1"`) |
+| `$.Target` | `string` | 대상 파일 경로 |
+| `$.Type` | `string` | 관계 타입 URI |
+
+### `ExcelXmlWorkbookData`
+
+`workbook.xml` 데이터 구조이다.
+
+```typescript
+export interface ExcelXmlWorkbookData {
+  workbook: {
+    $: { "xmlns": string; "xmlns:r"?: string };
+    bookViews?: [{ workbookView: [{}] }];
+    sheets?: [{ sheet: { $: { "name": string; "sheetId": string; "r:id": string } }[] }];
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `workbook.$` | `object` | 네임스페이스 |
+| `workbook.bookViews` | `Array \| undefined` | 워크북 뷰 설정 |
+| `workbook.sheets` | `Array \| undefined` | 시트 목록 |
+| `workbook.sheets[0].sheet[].$.name` | `string` | 시트 이름 |
+| `workbook.sheets[0].sheet[].$.sheetId` | `string` | 시트 ID |
+| `workbook.sheets[0].sheet[].$["r:id"]` | `string` | 관계 ID |
+
+### `ExcelXmlWorksheetData`
+
+`worksheet*.xml` 데이터 구조이다.
+
+```typescript
+export interface ExcelXmlWorksheetData {
+  worksheet: {
+    $: { "xmlns": string; "xmlns:r"?: string };
+    dimension?: [{ $: { ref: string } }];
+    sheetViews?: [{ sheetView: { $: { workbookViewId: string; zoomScale?: string }; pane?: [...] }[] }];
+    sheetFormatPr?: [{ $: { defaultRowHeight: string } }];
+    cols?: [{ col: { $: { min: string; max: string; width?: string; bestFit?: string; customWidth?: string } }[] }];
+    sheetData: [{ row?: ExcelRowData[] }];
+    mergeCells?: [{ $: { count: string }; mergeCell: { $: { ref: string } }[] }];
+    drawing?: { $: { "r:id": string } }[];
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `worksheet.dimension` | `Array \| undefined` | 데이터 범위 (예: `"A1:C10"`) |
+| `worksheet.sheetViews` | `Array \| undefined` | 시트 뷰 설정 (줌, 틀 고정) |
+| `worksheet.sheetFormatPr` | `Array \| undefined` | 기본 행 높이 |
+| `worksheet.cols` | `Array \| undefined` | 열 설정 (너비 등) |
+| `worksheet.sheetData` | `Array` | 행 데이터 |
+| `worksheet.mergeCells` | `Array \| undefined` | 병합 셀 정보 |
+| `worksheet.drawing` | `Array \| undefined` | 드로잉 관계 참조 |
+
+### `ExcelRowData`
+
+행 XML 데이터이다.
+
+```typescript
+export interface ExcelRowData {
+  $: { r: string };
+  c?: ExcelCellData[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `$.r` | `string` | 행 주소 (1 기반, 예: `"1"`, `"10"`) |
+| `c` | `ExcelCellData[] \| undefined` | 셀 데이터 배열 |
+
+### `ExcelCellData`
+
+셀 XML 데이터이다.
+
+```typescript
+export interface ExcelCellData {
+  $: { r: string; s?: string; t?: ExcelCellType };
+  v?: [string];
+  f?: [string];
+  is?: { t?: (string | { _?: string })[] }[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `$.r` | `string` | 셀 주소 (예: `"A1"`, `"B3"`) |
+| `$.s` | `string \| undefined` | 스타일 ID |
+| `$.t` | `ExcelCellType \| undefined` | 셀 타입 |
+| `v` | `[string] \| undefined` | 셀 값 |
+| `f` | `[string] \| undefined` | 수식 |
+| `is` | `Array \| undefined` | 인라인 문자열 데이터 |
+
+### `ExcelXmlDrawingData`
+
+`drawing*.xml` 데이터 구조이다. 이미지 앵커 정보를 포함한다.
+
+```typescript
+export interface ExcelXmlDrawingData {
+  wsDr: {
+    $: { "xmlns": string; "xmlns:a"?: string; "xmlns:r"?: string };
+    twoCellAnchor?: {
+      from?: { col: string[]; colOff?: string[]; row: string[]; rowOff?: string[] }[];
+      to?: { col: string[]; colOff?: string[]; row: string[]; rowOff?: string[] }[];
+      pic?: { nvPicPr?: {...}[]; blipFill?: {...}[]; spPr?: {...}[] }[];
+      clientData?: unknown[];
+    }[];
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `wsDr.$` | `object` | 네임스페이스 |
+| `wsDr.twoCellAnchor` | `Array \| undefined` | 두 셀 사이에 앵커된 이미지 목록 |
+| `twoCellAnchor.from` | `Array \| undefined` | 시작 위치 (행/열/오프셋) |
+| `twoCellAnchor.to` | `Array \| undefined` | 끝 위치 (행/열/오프셋) |
+| `twoCellAnchor.pic` | `Array \| undefined` | 이미지 정보 (blip 관계 ID 포함) |
+
+### `ExcelXmlSharedStringData`
+
+`sharedStrings.xml` 데이터 구조이다.
+
+```typescript
+export interface ExcelXmlSharedStringData {
+  sst: {
+    $: { xmlns: string };
+    si?: ExcelXmlSharedStringDataSi[];
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sst.$` | `{ xmlns: string }` | 네임스페이스 |
+| `sst.si` | `ExcelXmlSharedStringDataSi[] \| undefined` | 공유 문자열 항목 배열 |
+
+### `ExcelXmlSharedStringDataSi`
+
+SharedString 개별 항목이다. discriminated union으로, `t` 키가 있으면 단순 텍스트, `r` 키가 있으면 서식 있는 텍스트(rich text)이다.
+
+```typescript
+export type ExcelXmlSharedStringDataSi =
+  | { t: ExcelXmlSharedStringDataText }
+  | { r: { t: ExcelXmlSharedStringDataText }[] };
+```
+
+| Variant | Discriminant | Description |
+|---------|-------------|-------------|
+| `{ t: ... }` | `t` 키 존재 | 단순 텍스트 |
+| `{ r: ... }` | `r` 키 존재 | 서식 있는 텍스트 (run 배열) |
+
+### `ExcelXmlSharedStringDataText`
+
+SharedString 텍스트 데이터이다. 단순 문자열 또는 공백 보존 속성이 있는 객체이다.
+
+```typescript
+export type ExcelXmlSharedStringDataText = [string | { $: { space?: "preserve" }; _?: string }];
+```
+
+### `ExcelXmlStyleData`
+
+`styles.xml` 데이터 구조이다.
+
+```typescript
+export interface ExcelXmlStyleData {
+  styleSheet: {
+    $: { xmlns: string };
+    numFmts?: [{ $: { count: string }; numFmt?: { $: { numFmtId: string; formatCode: string } }[] }];
+    fonts: [{ $: { count: string }; font: {}[] }];
+    fills: [{ $: { count: string }; fill: ExcelXmlStyleDataFill[] }];
+    borders: [{ $: { count: string }; border: ExcelXmlStyleDataBorder[] }];
+    cellXfs: [{ $: { count: string }; xf: ExcelXmlStyleDataXf[] }];
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `styleSheet.numFmts` | `Array \| undefined` | 커스텀 숫자 형식 목록 |
+| `styleSheet.fonts` | `Array` | 폰트 목록 |
+| `styleSheet.fills` | `Array` | 채우기 스타일 목록 |
+| `styleSheet.borders` | `Array` | 테두리 스타일 목록 |
+| `styleSheet.cellXfs` | `Array` | 셀 서식(xf) 목록 |
+
+### `ExcelXmlStyleDataXf`
+
+셀 서식(xf) 데이터이다.
+
+```typescript
+export 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" } }];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `$.numFmtId` | `string \| undefined` | 숫자 형식 ID |
+| `$.fontId` | `string \| undefined` | 폰트 ID |
+| `$.fillId` | `string \| undefined` | 채우기 ID |
+| `$.borderId` | `string \| undefined` | 테두리 ID |
+| `$.xfId` | `string \| undefined` | 부모 xf ID |
+| `$.applyNumberFormat` | `string \| undefined` | 숫자 형식 적용 여부 |
+| `$.applyFont` | `string \| undefined` | 폰트 적용 여부 |
+| `$.applyAlignment` | `string \| undefined` | 정렬 적용 여부 |
+| `$.applyFill` | `string \| undefined` | 채우기 적용 여부 |
+| `$.applyBorder` | `string \| undefined` | 테두리 적용 여부 |
+| `alignment` | `Array \| undefined` | 정렬 설정 (horizontal, vertical) |
+
+### `ExcelXmlStyleDataFill`
+
+채우기 스타일 데이터이다.
+
+```typescript
+export interface ExcelXmlStyleDataFill {
+  patternFill: [{ $: { patternType: "none" | "solid" | "gray125" }; fgColor?: [{ $: { rgb: string } }] }];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `patternFill[0].$.patternType` | `"none" \| "solid" \| "gray125"` | 패턴 유형 |
+| `patternFill[0].fgColor` | `[{ $: { rgb: string } }] \| undefined` | 전경색 (ARGB) |
+
+### `ExcelXmlStyleDataBorder`
+
+테두리 스타일 데이터이다. 각 방향은 선택적이며, `style`과 `color`를 가진다.
+
+```typescript
+export interface ExcelXmlStyleDataBorder {
+  top?: [{ $: { style: "thin" | "medium" }; color?: [{ $: { rgb: string } }] }];
+  left?: [{ $: { style: "thin" | "medium" }; color?: [{ $: { rgb: string } }] }];
+  right?: [{ $: { style: "thin" | "medium" }; color?: [{ $: { rgb: string } }] }];
+  bottom?: [{ $: { style: "thin" | "medium" }; color?: [{ $: { rgb: string } }] }];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `top` | `Array \| undefined` | 상단 테두리 (`"thin"` 또는 `"medium"`) |
+| `left` | `Array \| undefined` | 좌측 테두리 |
+| `right` | `Array \| undefined` | 우측 테두리 |
+| `bottom` | `Array \| undefined` | 하단 테두리 |

package/docs/utilities.md

@@ -0,0 +1,194 @@
+# Utilities
+
+## `ExcelUtils`
+
+Excel 유틸리티 함수 모음. 셀 주소 변환, 날짜/숫자 변환, 숫자 형식 처리 정적 메서드를 제공한다.
+
+```typescript
+export class ExcelUtils {
+  // 주소 변환
+  static stringifyAddr(point: ExcelAddressPoint): string;
+  static stringifyRowAddr(r: number): string;
+  static stringifyColAddr(c: number): string;
+  static parseRowAddr(addr: string): number;
+  static parseColAddr(addr: string): number;
+  static parseCellAddr(addr: string): ExcelAddressPoint;
+  static parseRangeAddr(rangeAddr: string): ExcelAddressRangePoint;
+  static stringifyRangeAddr(point: ExcelAddressRangePoint): string;
+
+  // 날짜/숫자 변환
+  static convertTimeTickToNumber(tick: number): number;
+  static convertNumberToTimeTick(value: number): number;
+
+  // 숫자 형식 처리
+  static convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat;
+  static convertNumFmtIdToName(numFmtId: number): ExcelNumberFormat;
+  static convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number;
+}
+```
+
+### 주소 변환 메서드
+
+#### `stringifyAddr(point)`
+
+셀 좌표를 "A1" 형식 문자열로 변환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `point` | `ExcelAddressPoint` | 셀 좌표 (`{ r: number; c: number }`) |
+
+**반환값:** `string` - 예: `{ r: 0, c: 0 }` -> `"A1"`, `{ r: 2, c: 3 }` -> `"D3"`
+
+#### `stringifyRowAddr(r)`
+
+행 인덱스(0 기반)를 행 주소 문자열로 변환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `r` | `number` | 행 인덱스 (0 기반) |
+
+**반환값:** `string` - 예: `0` -> `"1"`, `9` -> `"10"`
+
+#### `stringifyColAddr(c)`
+
+열 인덱스(0 기반)를 열 주소 문자열로 변환한다. 열 인덱스는 0~16383 범위여야 한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `c` | `number` | 열 인덱스 (0 기반) |
+
+**반환값:** `string` - 예: `0` -> `"A"`, `25` -> `"Z"`, `26` -> `"AA"`
+
+#### `parseRowAddr(addr)`
+
+셀 주소에서 행 인덱스를 추출한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `addr` | `string` | 셀 주소 (예: `"A3"`) |
+
+**반환값:** `number` - 0 기반 행 인덱스. 예: `"A3"` -> `2`
+
+#### `parseColAddr(addr)`
+
+셀 주소에서 열 인덱스를 추출한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `addr` | `string` | 셀 주소 (예: `"B3"`) |
+
+**반환값:** `number` - 0 기반 열 인덱스. 예: `"B3"` -> `1`
+
+#### `parseCellAddr(addr)`
+
+셀 주소를 좌표로 변환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `addr` | `string` | 셀 주소 (예: `"B3"`) |
+
+**반환값:** `ExcelAddressPoint` - 예: `"B3"` -> `{ r: 2, c: 1 }`
+
+#### `parseRangeAddr(rangeAddr)`
+
+범위 주소를 좌표로 변환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `rangeAddr` | `string` | 범위 주소 (예: `"A1:C3"`) |
+
+**반환값:** `ExcelAddressRangePoint` - 예: `"A1:C3"` -> `{ s: { r: 0, c: 0 }, e: { r: 2, c: 2 } }`
+
+#### `stringifyRangeAddr(point)`
+
+범위 좌표를 주소 문자열로 변환한다. 시작과 끝이 같으면 단일 셀 주소를 반환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `point` | `ExcelAddressRangePoint` | 범위 좌표 |
+
+**반환값:** `string` - 예: `"A1:C3"` 또는 `"A1"` (단일 셀)
+
+### 날짜/숫자 변환 메서드
+
+#### `convertTimeTickToNumber(tick)`
+
+JavaScript 타임스탬프(ms)를 Excel 날짜 숫자로 변환한다. Excel은 1900-01-01을 1로 계산한다 (1899-12-30이 날짜 0).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `tick` | `number` | JavaScript 타임스탬프 (밀리초) |
+
+**반환값:** `number` - Excel 날짜 숫자
+
+#### `convertNumberToTimeTick(value)`
+
+Excel 날짜 숫자를 JavaScript 타임스탬프(ms)로 변환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | `number` | Excel 날짜 숫자 |
+
+**반환값:** `number` - JavaScript 타임스탬프 (밀리초)
+
+### 숫자 형식 처리 메서드
+
+#### `convertNumFmtCodeToName(numFmtCode)`
+
+숫자 형식 코드를 형식 이름으로 변환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `numFmtCode` | `string` | 숫자 형식 코드 (예: `"General"`, `"yyyy-mm-dd"`) |
+
+**반환값:** `ExcelNumberFormat` - `"number"`, `"string"`, `"DateOnly"`, `"DateTime"`, `"Time"` 중 하나
+
+**변환 규칙:**
+
+| 형식 코드 패턴 | 반환값 |
+|----------------|--------|
+| `"General"` | `"number"` |
+| `yy`, `dd`, `mm`(날짜 문맥) 포함 + 시간 포함 | `"DateTime"` |
+| `yy`, `dd`, `mm`(날짜 문맥) 포함 | `"DateOnly"` |
+| `h`, `ss` 포함 | `"Time"` |
+| 숫자 패턴 (`0`, `#`, `.` 등) | `"number"` |
+
+#### `convertNumFmtIdToName(numFmtId)`
+
+Excel 내장 숫자 형식 ID를 형식 이름으로 변환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `numFmtId` | `number` | 숫자 형식 ID |
+
+**반환값:** `ExcelNumberFormat`
+
+**내장 형식 ID 범위:**
+
+| ID 범위 | 형식 |
+|---------|------|
+| 0~13, 37~40, 48 | `"number"` (숫자/일반/통화/퍼센트) |
+| 14~17, 27~31, 34~36, 50~58 | `"DateOnly"` (날짜, 로컬라이즈 포함) |
+| 22 | `"DateTime"` (날짜+시간) |
+| 18~21, 32~33, 45~47 | `"Time"` (시간) |
+| 49 | `"string"` (텍스트) |
+
+#### `convertNumFmtNameToId(numFmtName)`
+
+숫자 형식 이름을 형식 ID로 변환한다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `numFmtName` | `ExcelNumberFormat` | 형식 이름 |
+
+**반환값:** `number`
+
+**매핑:**
+
+| 형식 이름 | ID |
+|-----------|-----|
+| `"number"` | 0 |
+| `"DateOnly"` | 14 |
+| `"DateTime"` | 22 |
+| `"Time"` | 18 |
+| `"string"` | 49 |

package/docs/wrapper.md

@@ -0,0 +1,73 @@
+# Wrapper
+
+## `ExcelWrapper`
+
+Zod 스키마 기반 타입 안전한 Excel 읽기/쓰기 래퍼. 스키마에서 타입 정보를 추론하여 타입 안전한 읽기/쓰기를 제공한다.
+
+```typescript
+export class ExcelWrapper<TSchema extends z.ZodObject<z.ZodRawShape>> {
+  constructor(schema: TSchema);
+
+  async read(
+    file: Bytes | Blob,
+    wsNameOrIndex?: string | number,
+    options?: { excludes?: (keyof z.infer<TSchema>)[] },
+  ): Promise<z.infer<TSchema>[]>;
+
+  async write(
+    wsName: string,
+    records: Partial<z.infer<TSchema>>[],
+    options?: { excludes?: (keyof z.infer<TSchema>)[] },
+  ): Promise<ExcelWorkbook>;
+}
+```
+
+### Constructor
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `schema` | `TSchema extends z.ZodObject<z.ZodRawShape>` | Zod 스키마. `.describe()`로 Excel 헤더 이름을 지정한다 |
+
+### Methods
+
+#### `read(file, wsNameOrIndex?, options?)`
+
+Excel 파일을 레코드 배열로 읽는다. 헤더 행의 텍스트를 스키마의 `.describe()` 값과 매칭하여 필드를 연결한다. Zod 스키마로 유효성 검사를 수행하며, 실패 시 에러를 던진다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `file` | `Bytes \| Blob` | Excel 파일 데이터 |
+| `wsNameOrIndex` | `string \| number` | 워크시트 이름 또는 0 기반 인덱스 (기본값: `0`) |
+| `options.excludes` | `(keyof z.infer<TSchema>)[]` | 읽기에서 제외할 필드 키 배열 |
+
+**반환값:** `z.infer<TSchema>[]` - 스키마 타입으로 추론된 레코드 배열
+
+**타입 변환 규칙:**
+
+| 스키마 타입 | 변환 동작 |
+|------------|-----------|
+| `z.string()` | 문자열로 변환 (`String(rawValue)`) |
+| `z.number()` | 숫자로 파싱 (`num.parseFloat`) |
+| `z.boolean()` | `"1"`, `"true"` -> `true`, `"0"`, `"false"` -> `false` |
+| `z.optional()` / `z.nullable()` | 빈 셀을 `undefined`로 반환 |
+| `z.default(value)` | 빈 셀에 기본값 적용 |
+| `DateOnly` / `DateTime` / `Time` | `instanceof`로 직접 전달 |
+
+#### `write(wsName, records, options?)`
+
+레코드 배열을 Excel 워크북으로 변환한다. 반환된 `ExcelWorkbook`의 리소스 관리는 호출자의 책임이다. 내부에서 에러 발생 시 워크북이 자동으로 `close()`된다.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `wsName` | `string` | 워크시트 이름 |
+| `records` | `Partial<z.infer<TSchema>>[]` | 레코드 배열 |
+| `options.excludes` | `(keyof z.infer<TSchema>)[]` | 쓰기에서 제외할 필드 키 배열 |
+
+**반환값:** `ExcelWorkbook` - 호출자가 `try-finally` 블록에서 `close()`를 호출하여 리소스를 관리해야 한다
+
+**쓰기 동작:**
+
+- 첫 번째 행에 헤더 자동 생성 (스키마의 `.describe()` 값 사용)
+- 모든 셀에 테두리 스타일 자동 적용
+- 필수 비boolean 필드의 헤더에 노란색 배경(`00FFFF00`) 강조
+- 확대/축소 85%, 첫 번째 행 틀 고정 자동 설정

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/excel",
-  "version": "14.0.47",
+  "version": "14.0.49",
   "description": "심플리즘 패키지 - 엑셀 (neutral)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,7 +14,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "sideEffects": false,
   "devDependencies": {
@@ -23,6 +24,6 @@
   "dependencies": {
     "mime": "^4.1.0",
     "zod": "^4.3.6",
-    "@simplysm/core-common": "14.0.47"
+    "@simplysm/core-common": "14.0.49"
   }
 }

package/src/xml/excel-xml-workbook.ts

@@ -120,7 +120,7 @@ export class ExcelXmlWorkbook implements ExcelXml {
   }
 
   private _getReplacedName(name: string): string {
-    //-- 잘못된 시트 이름 문자를 "_"로 대체
-    return name.replace(/[:\\/?*\[\]']/g, "_");
+    //-- 잘못된 시트 이름 문자 제거. 전부 제거되어 빈 문자열이 되면 "Sheet" 사용.
+    return name.replace(/[:\\/?*\[\]']/g, "") || "Sheet";
   }
 }