@simplysm/excel 14.0.49 → 14.0.51

package/docs/types/excel-xml-shared-string-data.md

@@ -0,0 +1,42 @@
+# ExcelXmlSharedStringData
+
+`sharedStrings.xml` 데이터 구조이다. 내부 구현에 사용된다.
+
+```typescript
+export interface ExcelXmlSharedStringData {
+  sst: {
+    $: { xmlns: string };
+    si?: ExcelXmlSharedStringDataSi[];
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sst.$` | `{ xmlns: string }` | 네임스페이스 |
+| `sst.si` | `ExcelXmlSharedStringDataSi[] \| undefined` | 공유 문자열 항목 배열 |
+
+## Related Types
+
+### `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 }];
+```

package/docs/types/excel-xml-style-data.md

@@ -0,0 +1,97 @@
+# 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) 목록 |
+
+## Related Types
+
+### `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/types/excel-xml-workbook-data.md

@@ -0,0 +1,22 @@
+# 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 |

package/docs/types/excel-xml-worksheet-data.md

@@ -0,0 +1,68 @@
+# ExcelXmlWorksheetData
+
+`worksheet*.xml` 데이터 구조이다. 내부 구현에 사용된다.
+
+```typescript
+export interface ExcelXmlWorksheetData {
+  worksheet: {
+    $: { "xmlns": string; "xmlns:r"?: string };
+    dimension?: [{ $: { ref: string } }];
+    sheetViews?: [{ sheetView: { $: { workbookViewId: string; zoomScale?: string }; pane?: [{ $: { xSplit?: string; ySplit?: string; topLeftCell?: string; activePane?: string; state?: string } }] }[] }];
+    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` | 드로잉 관계 참조 |
+
+## Related Types
+
+### `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` | 인라인 문자열 데이터 |

package/docs/types/excel-xml.md

@@ -0,0 +1,15 @@
+# ExcelXml
+
+XML 처리 클래스가 구현하는 인터페이스이다. `xml/` 디렉터리의 내부 클래스들이 이를 구현한다. 외부에서 직접 사용하지 않는다.
+
+```typescript
+export interface ExcelXml {
+  readonly data: unknown;
+  cleanup(): void;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `data` | `unknown` | XML 파싱된 데이터 (read-only) |
+| `cleanup` | `() => void` | `ZipCache.toBytes()` 직전에 호출되어 직렬화 전 데이터를 정리한다 |

package/docs/utilities/excel-utils.md

@@ -0,0 +1,93 @@
+# 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;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `stringifyAddr` | static | `(point: ExcelAddressPoint) => string` | 셀 좌표를 "A1" 형식 문자열로 변환 |
+| `stringifyRowAddr` | static | `(r: number) => string` | 행 인덱스(0 기반)를 행 주소 문자열로 변환 |
+| `stringifyColAddr` | static | `(c: number) => string` | 열 인덱스(0 기반)를 열 주소 문자열로 변환. 범위: 0~16383 |
+| `parseRowAddr` | static | `(addr: string) => number` | 셀 주소에서 0 기반 행 인덱스 추출 |
+| `parseColAddr` | static | `(addr: string) => number` | 셀 주소에서 0 기반 열 인덱스 추출 |
+| `parseCellAddr` | static | `(addr: string) => ExcelAddressPoint` | 셀 주소를 좌표로 변환 |
+| `parseRangeAddr` | static | `(rangeAddr: string) => ExcelAddressRangePoint` | 범위 주소를 좌표로 변환 |
+| `stringifyRangeAddr` | static | `(point: ExcelAddressRangePoint) => string` | 범위 좌표를 주소 문자열로 변환. 시작=끝이면 단일 셀 주소 반환 |
+| `convertTimeTickToNumber` | static | `(tick: number) => number` | JavaScript 타임스탬프(ms)를 Excel 날짜 숫자로 변환 |
+| `convertNumberToTimeTick` | static | `(value: number) => number` | Excel 날짜 숫자를 JavaScript 타임스탬프(ms)로 변환 |
+| `convertNumFmtCodeToName` | static | `(numFmtCode: string) => ExcelNumberFormat` | 숫자 형식 코드를 형식 이름으로 변환 |
+| `convertNumFmtIdToName` | static | `(numFmtId: number) => ExcelNumberFormat` | Excel 내장 숫자 형식 ID를 형식 이름으로 변환 |
+| `convertNumFmtNameToId` | static | `(numFmtName: ExcelNumberFormat) => number` | 숫자 형식 이름을 형식 ID로 변환 |
+
+## Usage
+
+```typescript
+import { ExcelUtils } from "@simplysm/excel";
+
+// 주소 변환
+ExcelUtils.stringifyAddr({ r: 0, c: 0 });   // "A1"
+ExcelUtils.stringifyAddr({ r: 2, c: 3 });   // "D3"
+ExcelUtils.parseCellAddr("B3");             // { r: 2, c: 1 }
+ExcelUtils.parseRangeAddr("A1:C3");         // { s: { r: 0, c: 0 }, e: { r: 2, c: 2 } }
+ExcelUtils.stringifyRangeAddr({ s: { r: 0, c: 0 }, e: { r: 2, c: 2 } }); // "A1:C3"
+
+ExcelUtils.stringifyRowAddr(0);  // "1"
+ExcelUtils.stringifyColAddr(0);  // "A"
+ExcelUtils.stringifyColAddr(26); // "AA"
+ExcelUtils.parseRowAddr("A3");   // 2
+ExcelUtils.parseColAddr("B3");   // 1
+```
+
+## `convertNumFmtCodeToName` 변환 규칙
+
+| 형식 코드 패턴 | 반환값 |
+|----------------|--------|
+| `"General"` | `"number"` |
+| `yy`, `dd`, `mm`(날짜 문맥) 포함 + 시간(`h`, `ss`) 포함 | `"DateTime"` |
+| `yy`, `dd`, `mm`(날짜 문맥) 포함 | `"DateOnly"` |
+| `h`, `ss` 포함 | `"Time"` |
+| 숫자 패턴 (`0`, `#`, `.` 등) | `"number"` |
+
+## `convertNumFmtIdToName` 내장 형식 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` 매핑
+
+| 형식 이름 | ID |
+|-----------|-----|
+| `"number"` | 0 |
+| `"DateOnly"` | 14 |
+| `"DateTime"` | 22 |
+| `"Time"` | 18 |
+| `"string"` | 49 |

package/docs/wrapper/excel-wrapper.md

@@ -0,0 +1,100 @@
+# 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>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `constructor` | method | `(schema: TSchema) => ExcelWrapper<TSchema>` | Zod 스키마를 받아 인스턴스 생성. `.describe()`로 Excel 헤더 이름을 지정한다 |
+| `read` | method | `(file, wsNameOrIndex?, options?) => Promise<z.infer<TSchema>[]>` | Excel 파일을 레코드 배열로 읽기. 스키마 유효성 검사 수행 |
+| `write` | method | `(wsName, records, options?) => Promise<ExcelWorkbook>` | 레코드 배열을 Excel 워크북으로 변환. 반환된 워크북의 `close()`는 호출자 책임 |
+
+## Parameters
+
+### `read(file, wsNameOrIndex?, options?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `file` | `Bytes \| Blob` | Excel 파일 데이터 |
+| `wsNameOrIndex` | `string \| number` | 워크시트 이름 또는 0 기반 인덱스 (기본값: `0`) |
+| `options.excludes` | `(keyof z.infer<TSchema>)[] \| undefined` | 읽기에서 제외할 필드 키 배열 |
+
+**타입 변환 규칙:**
+
+| 스키마 타입 | 변환 동작 |
+|------------|-----------|
+| `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?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `wsName` | `string` | 워크시트 이름 |
+| `records` | `Partial<z.infer<TSchema>>[]` | 레코드 배열 |
+| `options.excludes` | `(keyof z.infer<TSchema>)[] \| undefined` | 쓰기에서 제외할 필드 키 배열 |
+
+**쓰기 동작:**
+
+- 첫 번째 행에 헤더 자동 생성 (스키마의 `.describe()` 값 사용)
+- 모든 셀에 테두리 스타일 자동 적용
+- 필수 비boolean 필드의 헤더에 노란색 배경(`00FFFF00`) 강조
+- 확대/축소 85%, 첫 번째 행 틀 고정 자동 설정
+- 내부에서 에러 발생 시 워크북이 자동으로 `close()`됨
+
+## Usage
+
+```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("이메일"),
+  active: z.boolean().default(false).describe("활성"),
+});
+
+const wrapper = new ExcelWrapper(schema);
+
+// 쓰기 (시트명, 레코드 배열)
+const wb = await wrapper.write("사람", [
+  { name: "김철수", age: 30, email: "kim@example.com" },
+  { name: "이영희", age: 28 },
+]);
+try {
+  const bytes = await wb.toBytes();
+} finally {
+  await wb.close();
+}
+
+// 읽기 (시트명 또는 인덱스, 기본값: 0)
+const records = await wrapper.read(bytes, "사람");
+// z.infer<typeof schema>[] 타입으로 반환
+
+// excludes 옵션으로 특정 필드 제외
+const filtered = await wrapper.read(bytes, 0, { excludes: ["email"] });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/excel",
-  "version": "14.0.49",
+  "version": "14.0.51",
   "description": "심플리즘 패키지 - 엑셀 (neutral)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -24,6 +24,6 @@
   "dependencies": {
     "mime": "^4.1.0",
     "zod": "^4.3.6",
-    "@simplysm/core-common": "14.0.49"
+    "@simplysm/core-common": "14.0.51"
   }
 }