@simplysm/excel 13.0.99 → 14.0.1

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

@@ -16,8 +16,8 @@ interface RowInfo {
 }
 
 /**
- * Class managing xl/worksheets/sheet*.xml files.
- * Handles cell data, merges, column widths, row heights, etc.
+ * xl/worksheets/sheet*.xml 파일을 관리하는 클래스.
+ * 셀 데이터, 병합, 열 너비, 행 높이 등을 처리한다.
  */
 export class ExcelXmlWorksheet implements ExcelXml {
   data: ExcelXmlWorksheetData;
@@ -131,21 +131,21 @@ export class ExcelXmlWorksheet implements ExcelXml {
   }
 
   deleteCell(addr: { r: number; c: number }): void {
-    // No-op if ROW does not exist
+    // 행이 존재하지 않으면 아무 작업도 하지 않음
     const rowInfo = this._dataMap.get(addr.r);
     if (rowInfo == null) return;
 
-    // No-op if CELL does not exist
+    // 셀이 존재하지 않으면 아무 작업도 하지 않음
     const cellData = rowInfo.cellMap.get(addr.c);
     if (cellData == null) return;
 
-    // Delete CELL
+    // 셀 삭제
     const cellsData = rowInfo.data.c!;
     const cellIndex = cellsData.indexOf(cellData);
     if (cellIndex !== -1) cellsData.splice(cellIndex, 1);
     rowInfo.cellMap.delete(addr.c);
 
-    // Delete ROW if it was the last CELL
+    // 마지막 셀이었으면 행도 삭제
     if (rowInfo.cellMap.size === 0) {
       this._deleteRow(addr.r);
     }
@@ -161,7 +161,7 @@ export class ExcelXmlWorksheet implements ExcelXml {
 
     const newRange = { s: startAddr, e: endAddr };
 
-    // Check for merge overlap
+    // 병합 겹침 검사
     const existingMergeCells = mergeCells[0].mergeCell;
     for (const mergeCell of existingMergeCells) {
       const existingRange = ExcelUtils.parseRangeAddr(mergeCell.$.ref);
@@ -173,7 +173,7 @@ export class ExcelXmlWorksheet implements ExcelXml {
         newRange.e.c >= existingRange.s.c
       ) {
         throw new Error(
-          `Merged cell overlaps with existing merge range (${mergeCell.$.ref}): ${ExcelUtils.stringifyRangeAddr(newRange)}`,
+          `셀 병합이 기존 병합 범위와 겹칩니다 (${mergeCell.$.ref}): ${ExcelUtils.stringifyRangeAddr(newRange)}`,
         );
       }
     }
@@ -181,7 +181,7 @@ export class ExcelXmlWorksheet implements ExcelXml {
     mergeCells[0].mergeCell.push({ $: { ref: ExcelUtils.stringifyRangeAddr(newRange) } });
     mergeCells[0].$.count = mergeCells[0].mergeCell.length.toString();
 
-    // Delete all cells except the start cell
+    // 시작 셀을 제외한 모든 셀 삭제
     for (let r = startAddr.r; r <= endAddr.r; r++) {
       for (let c = startAddr.c; c <= endAddr.c; c++) {
         const currentAddr = { r, c };
@@ -240,23 +240,23 @@ export class ExcelXmlWorksheet implements ExcelXml {
   }
 
   /**
-   * Set width of a specific column.
+   * 특정 열의 너비를 설정한다.
    *
    * @internal
-   * Use ExcelCol.setWidth() externally.
+   * 외부에서는 ExcelCol.setWidth()를 사용할 것.
    *
-   * @param colIndex Column index (1-based, string)
-   * @param width Width to set
+   * @param colIndex 열 인덱스 (1 기반, 문자열)
+   * @param width 설정할 너비
    */
   setColWidth(colIndex: string, width: string): void {
     const colIndexNumber = num.parseInt(colIndex);
     if (colIndexNumber == null) {
-      throw new Error(`Invalid column index: ${colIndex}`);
+      throw new Error(`잘못된 열 인덱스: ${colIndex}`);
     }
 
     const cols = this.data.worksheet.cols?.[0];
 
-    // Find existing range containing the target column
+    // 대상 열을 포함하는 기존 범위 찾기
     const col = cols
       ? cols.col.single(
           (item) =>
@@ -267,20 +267,20 @@ export class ExcelXmlWorksheet implements ExcelXml {
 
     if (col != null && cols != null) {
       if (col.$.min === col.$.max) {
-        // Single column range: update properties of that column only
+        // 단일 열 범위: 해당 열의 속성만 갱신
         col.$.bestFit = "1";
         col.$.customWidth = "1";
         col.$.width = width;
       } else {
-        // Multi-column range: split the range and apply new width only to target column
-        // e.g.: existing [1~5, width=10], target=3, new width=20
+        // 다중 열 범위: 범위를 분할하고 대상 열에만 새 너비 적용
+        // 예: 기존 [1~5, width=10], 대상=3, 새 너비=20
         //     -> [1~2, width=10], [3, width=20], [4~5, width=10]
         const minNumber = num.parseInt(col.$.min) ?? 0;
         const maxNumber = num.parseInt(col.$.max) ?? 0;
 
         let insertIndex = cols.col.indexOf(col);
 
-        // Create front range (min ~ colIndex-1): keep original properties
+        // 앞쪽 범위 생성 (min ~ colIndex-1): 원래 속성 유지
         if (minNumber < colIndexNumber) {
           cols.col.splice(insertIndex, 0, {
             $: {
@@ -292,7 +292,7 @@ export class ExcelXmlWorksheet implements ExcelXml {
           insertIndex++;
         }
 
-        // Create target column (colIndex): apply new width
+        // 대상 열 생성 (colIndex): 새 너비 적용
         cols.col.splice(insertIndex, 0, {
           $: {
             min: colIndex,
@@ -304,7 +304,7 @@ export class ExcelXmlWorksheet implements ExcelXml {
         });
         insertIndex++;
 
-        // Create back range (colIndex+1 ~ max): keep original properties
+        // 뒤쪽 범위 생성 (colIndex+1 ~ max): 원래 속성 유지
         if (maxNumber > colIndexNumber) {
           cols.col.splice(insertIndex, 0, {
             $: {
@@ -315,12 +315,12 @@ export class ExcelXmlWorksheet implements ExcelXml {
           });
         }
 
-        // Delete original range
+        // 원래 범위 삭제
         const colIndex2 = cols.col.indexOf(col);
         if (colIndex2 !== -1) cols.col.splice(colIndex2, 1);
       }
     } else {
-      // No existing range: create new range
+      // 기존 범위 없음: 새 범위 생성
       this.data.worksheet.cols = this.data.worksheet.cols ?? [{ col: [] }];
       this.data.worksheet.cols[0].col.push({
         $: {
@@ -372,17 +372,17 @@ export class ExcelXmlWorksheet implements ExcelXml {
   }
 
   copyRow(sourceR: number, targetR: number, options?: { skipMerge?: boolean }): void {
-    // Clone source ROW data
+    // 원본 행 데이터 복제
     const sourceRowInfo = this._dataMap.get(sourceR);
 
     if (sourceRowInfo != null) {
-      // Clone rowData
+      // 행 데이터 복제
       const newRowData: ExcelRowData = obj.clone(sourceRowInfo.data);
 
-      // Update ROW address
+      // 행 주소 갱신
       newRowData.$.r = ExcelUtils.stringifyRowAddr(targetR);
 
-      // Update each CELL address
+      // 각 셀 주소 갱신
       if (newRowData.c != null) {
         for (const cellData of newRowData.c) {
           const colAddr = ExcelUtils.parseColAddr(cellData.$.r);
@@ -395,26 +395,26 @@ export class ExcelXmlWorksheet implements ExcelXml {
       this._deleteRow(targetR);
     }
 
-    // Skip merge handling if skipMerge option is true
+    // skipMerge 옵션이 true이면 병합 처리 건너뛰기
     if (options?.skipMerge === true) {
       return;
     }
 
     const allMergeCells = this.getMergeCells();
 
-    // Copy and store source row merge cell info first
+    // 원본 행의 병합 셀 정보를 먼저 복사하여 저장
     const sourceMergeCells = allMergeCells
       .filter((mc) => mc.s.r <= sourceR && mc.e.r >= sourceR)
       .map((mc) => ({ s: { ...mc.s }, e: { ...mc.e } }));
 
-    // Remove existing merge cells in target row
+    // 대상 행의 기존 병합 셀 제거
     for (const mergeCell of allMergeCells) {
       if (mergeCell.s.r <= targetR && mergeCell.e.r >= targetR) {
         this.removeMergeCells(mergeCell.s, mergeCell.e);
       }
     }
 
-    // Copy stored source merge info to target
+    // 저장된 원본 병합 정보를 대상에 복사
     for (const mergeCell of sourceMergeCells) {
       const rowDiff = targetR - sourceR;
       const newStartAddr = { r: mergeCell.s.r + rowDiff, c: mergeCell.s.c };
@@ -438,7 +438,7 @@ export class ExcelXmlWorksheet implements ExcelXml {
   cleanup(): void {
     const result = {} as ExcelXmlWorksheetData["worksheet"];
 
-    // Sort order (around "sheetData", keep others in original position)
+    // 정렬 순서 ("sheetData" 기준, 나머지는 원래 위치 유지)
 
     for (const key of Object.keys(this.data.worksheet)) {
       if (key === "mergeCells") continue;
@@ -468,11 +468,11 @@ export class ExcelXmlWorksheet implements ExcelXml {
       }
     }
 
-    // Sort ROWs
+    // 행 정렬
     const rowsData = (result.sheetData[0].row = result.sheetData[0].row ?? []);
     rowsData.sort((a, b) => (num.parseInt(a.$.r) ?? 0) - (num.parseInt(b.$.r) ?? 0));
 
-    // Sort CELLs
+    // 셀 정렬
     for (const rowData of rowsData) {
       const cellsData = rowData.c;
       if (cellsData == null) continue;
@@ -481,7 +481,7 @@ export class ExcelXmlWorksheet implements ExcelXml {
       );
     }
 
-    // Apply dimension value
+    // dimension 값 적용
     if (result.dimension != null) {
       result.dimension[0].$.ref = ExcelUtils.stringifyRangeAddr(this.range);
     } else {
@@ -496,10 +496,10 @@ export class ExcelXmlWorksheet implements ExcelXml {
   }
 
   private _getOrCreateCellData(addr: { r: number; c: number }): ExcelCellData {
-    // Create ROW if it does not exist
+    // 행이 존재하지 않으면 생성
     const rowInfo = this._getOrCreateRowInfo(addr.r);
 
-    // Create CELL if it does not exist
+    // 셀이 존재하지 않으면 생성
     let cellData = rowInfo.cellMap.get(addr.c);
     if (cellData === undefined) {
       rowInfo.data.c = rowInfo.data.c ?? [];
@@ -523,11 +523,11 @@ export class ExcelXmlWorksheet implements ExcelXml {
   private _replaceRowData(r: number, rowData: ExcelRowData): RowInfo {
     this._deleteRow(r);
 
-    // Write to sheet
+    // 시트에 쓰기
     this.data.worksheet.sheetData[0].row = this.data.worksheet.sheetData[0].row ?? [];
     this.data.worksheet.sheetData[0].row.push(rowData);
 
-    // Write to cache
+    // 캐시에 쓰기
     const rowInfo = {
       data: rowData,
       cellMap: (rowData.c ?? []).toMap(
@@ -543,14 +543,14 @@ export class ExcelXmlWorksheet implements ExcelXml {
   private _replaceCellData(addr: { r: number; c: number }, cellData: ExcelCellData): void {
     this.deleteCell(addr);
 
-    // ROW
+    // 행
     const targetRowInfo = this._getOrCreateRowInfo(addr.r);
 
-    // Write to sheet
+    // 시트에 쓰기
     targetRowInfo.data.c = targetRowInfo.data.c ?? [];
     targetRowInfo.data.c.push(cellData);
 
-    // Write to cache
+    // 캐시에 쓰기
     targetRowInfo.cellMap.set(addr.c, cellData);
   }
 
@@ -565,7 +565,7 @@ export class ExcelXmlWorksheet implements ExcelXml {
     }
     this._dataMap.delete(r);
 
-    // Delete the row section from XML if no ROWs remain
+    // 행이 남아있지 않으면 XML에서 행 섹션 삭제
     if (this.data.worksheet.sheetData[0].row?.length === 0) {
       delete this.data.worksheet.sheetData[0].row;
     }

package/README.md

@@ -1,119 +0,0 @@
-# @simplysm/excel
-
-Excel file processing library. Platform-neutral (works in both browser and Node.js).
-
-## Installation
-
-```bash
-npm install @simplysm/excel
-```
-
-## 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");
-await ws.cell(0, 1).setValue("Age");
-await ws.cell(1, 0).setValue("Alice");
-await ws.cell(1, 1).setValue(30);
-const bytes = await wb.toBytes();
-```
-
-### Read an existing workbook
-
-```typescript
-await using wb = new ExcelWorkbook(fileBytes);
-const ws = await wb.getWorksheet(0);
-const value = await ws.cell(0, 0).getValue();
-const dataTable = await ws.getDataTable();
-```
-
-### Type-safe read/write with Zod schema
-
-```typescript
-import { z } from "zod";
-import { ExcelWrapper } from "@simplysm/excel";
-
-const schema = z.object({
-  name: z.string().describe("Name"),
-  age: z.number().describe("Age"),
-});
-
-const wrapper = new ExcelWrapper(schema);
-
-// Read
-const records = await wrapper.read(fileBytes);
-
-// Write
-await using wb = await wrapper.write("Sheet1", [
-  { name: "Alice", age: 30 },
-]);
-const bytes = await wb.toBytes();
-```