@simplysm/excel 14.0.100 → 14.0.101

package/src/excel-worksheet.ts

@@ -5,24 +5,22 @@ import mime from "mime";
 import { ExcelCell } from "./excel-cell";
 import { ExcelCol } from "./excel-col";
 import { ExcelRow } from "./excel-row";
+import type { IContentTypeModel } from "./models/i-content-type-model";
+import type { IDrawingModel } from "./models/i-drawing-model";
+import type { IRelationshipModel } from "./models/i-relationship-model";
+import type { ISharedStringModel } from "./models/i-shared-string-model";
+import type { IStyleModel } from "./models/i-style-model";
+import type { IWorkbookModel } from "./models/i-workbook-model";
+import type { IWorksheetModel } from "./models/i-worksheet-model";
+import type { ICfRuleSpec } from "./models/shared/excel-cf-spec";
 import type {
   ExcelAddressPoint,
   ExcelAddressRangePoint,
   ExcelConditionalRule,
   ExcelValueType,
-  ExcelXmlCfRuleData,
 } from "./types";
 import { ExcelUtils } from "./utils/excel-utils";
 import type { ZipCache } from "./utils/zip-cache";
-import type { ExcelXmlContentType } from "./xml/excel-xml-content-type";
-import { ExcelXmlDrawing } from "./xml/excel-xml-drawing";
-import { ExcelXmlRelationship } from "./xml/excel-xml-relationship";
-import type { ExcelXmlSharedString } from "./xml/excel-xml-shared-string";
-import { ExcelXmlSharedString as ExcelXmlSharedStringClass } from "./xml/excel-xml-shared-string";
-import type { ExcelXmlStyle } from "./xml/excel-xml-style";
-import { ExcelXmlStyle as ExcelXmlStyleClass } from "./xml/excel-xml-style";
-import type { ExcelXmlWorkbook } from "./xml/excel-xml-workbook";
-import type { ExcelXmlWorksheet } from "./xml/excel-xml-worksheet";
 
 /**
  * Excel 워크시트를 나타내는 클래스.
@@ -339,17 +337,6 @@ export class ExcelWorksheet {
    * @remarks
    * 같은 시트에 여러 번 호출하면 호출마다 `<conditionalFormatting>` 블록이 누적된다.
    * 정적 셀 스타일과 조건부 서식의 합성은 Excel native CF 오버레이에 위임한다.
-   *
-   * @example
-   * ```typescript
-   * await ws.addConditionalFormat({
-   *   ref: "B2:B100",
-   *   rules: [
-   *     { type: "cellIs", op: "<", value: 1000, style: { background: "00FF0000" } },
-   *     { type: "cellIs", op: "<", value: 4999, style: { background: "00FFFF00" } },
-   *   ],
-   * });
-   * ```
    */
   async addConditionalFormat(opts: {
     ref: string;
@@ -361,15 +348,7 @@ export class ExcelWorksheet {
     const styleData = await this._ensureStyleData();
     const topLeft = opts.ref.split(":")[0];
 
-    const dxfRules: {
-      dxfId: string;
-      cfRule: {
-        type: ExcelXmlCfRuleData["$"]["type"];
-        operator?: ExcelXmlCfRuleData["$"]["operator"];
-        formula: string[];
-        text?: string;
-      };
-    }[] = [];
+    const dxfRules: { dxfId: string; cfRule: ICfRuleSpec }[] = [];
 
     for (const rule of opts.rules) {
       const dxfId = styleData.addDxf(rule.style);
@@ -383,12 +362,7 @@ export class ExcelWorksheet {
   private static _buildCfRuleSpec(
     rule: ExcelConditionalRule,
     topLeft: string,
-  ): {
-    type: ExcelXmlCfRuleData["$"]["type"];
-    operator?: ExcelXmlCfRuleData["$"]["operator"];
-    formula: string[];
-    text?: string;
-  } {
+  ): ICfRuleSpec {
     const encodeLiteral = (v: number | string): string =>
       typeof v === "number" ? v.toString() : `"${v.replaceAll('"', '""')}"`;
 
@@ -434,7 +408,7 @@ export class ExcelWorksheet {
       }
     }
 
-    const operator: ExcelXmlCfRuleData["$"]["operator"] = (() => {
+    const operator: ICfRuleSpec["operator"] = (() => {
       switch (rule.op) {
         case "<":
           return "lessThan";
@@ -493,36 +467,34 @@ export class ExcelWorksheet {
     this._zipCache.set(mediaPath, opts.bytes);
 
     // 2. [Content_Types].xml 갱신
-    const typeXml = (await this._zipCache.get("[Content_Types].xml")) as ExcelXmlContentType;
+    const typeXml = (await this._zipCache.get("[Content_Types].xml")) as IContentTypeModel;
     typeXml.add(`/xl/media/image${mediaIndex}.${opts.ext}`, mimeType);
 
     // 3. 워크시트의 기존 drawing 확인
     const wsXml = await this._getWsData();
     const sheetRelsPath = `xl/worksheets/_rels/${this._targetFileName}.rels`;
-    let sheetRels = (await this._zipCache.get(sheetRelsPath)) as ExcelXmlRelationship | undefined;
+    let sheetRels = (await this._zipCache.get(sheetRelsPath)) as IRelationshipModel | undefined;
 
     // 기존 drawing 찾기
     let drawingIndex: number | undefined;
     let drawingPath: string | undefined;
-    let drawing: ExcelXmlDrawing | undefined;
-    let drawingRels: ExcelXmlRelationship | undefined;
+    let drawing: IDrawingModel | undefined;
+    let drawingRels: IRelationshipModel | undefined;
 
     if (sheetRels != null) {
-      const existingDrawingRel = sheetRels.data.Relationships.Relationship?.find(
-        (r) =>
-          r.$.Type ===
-          "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing",
+      const existingDrawingRel = sheetRels.findRelByType(
+        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing",
       );
       if (existingDrawingRel != null) {
         // 기존 drawing 경로에서 인덱스 추출
-        const match = existingDrawingRel.$.Target.match(/drawing(\d+)\.xml$/);
+        const match = existingDrawingRel.target.match(/drawing(\d+)\.xml$/);
         if (match != null) {
           drawingIndex = parseInt(match[1], 10);
           drawingPath = `xl/drawings/drawing${drawingIndex}.xml`;
-          drawing = (await this._zipCache.get(drawingPath)) as ExcelXmlDrawing | undefined;
+          drawing = (await this._zipCache.get(drawingPath)) as IDrawingModel | undefined;
           drawingRels = (await this._zipCache.get(
             `xl/drawings/_rels/drawing${drawingIndex}.xml.rels`,
-          )) as ExcelXmlRelationship | undefined;
+          )) as IRelationshipModel | undefined;
         }
       }
     }
@@ -534,13 +506,13 @@ export class ExcelWorksheet {
         drawingIndex++;
       }
       drawingPath = `xl/drawings/drawing${drawingIndex}.xml`;
-      drawing = new ExcelXmlDrawing();
+      drawing = this._zipCache.createDrawing();
 
       // [Content_Types].xml에 drawing 타입 추가
       typeXml.add("/" + drawingPath, "application/vnd.openxmlformats-officedocument.drawing+xml");
 
       // 워크시트 rels에 drawing 추가
-      sheetRels = sheetRels ?? new ExcelXmlRelationship();
+      sheetRels = sheetRels ?? this._zipCache.createRelationship();
       const sheetRelNum = sheetRels.addAndGetId(
         `../drawings/drawing${drawingIndex}.xml`,
         "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing",
@@ -549,16 +521,12 @@ export class ExcelWorksheet {
       this._zipCache.set(sheetRelsPath, sheetRels);
 
       // 워크시트 XML에 drawing 추가
-      wsXml.data.worksheet.$["xmlns:r"] =
-        wsXml.data.worksheet.$["xmlns:r"] ??
-        "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
-      wsXml.data.worksheet.drawing = wsXml.data.worksheet.drawing ?? [];
-      wsXml.data.worksheet.drawing.push({ $: { "r:id": drawingRelIdOnWorksheet } });
+      wsXml.setDrawingRelId(drawingRelIdOnWorksheet);
       this._zipCache.set(`xl/worksheets/${this._targetFileName}`, wsXml);
     }
 
     // 5. drawing rels 준비 (없으면 생성)
-    drawingRels = drawingRels ?? new ExcelXmlRelationship();
+    drawingRels = drawingRels ?? this._zipCache.createRelationship();
     const mediaFileName = mediaPath.slice(3);
     const drawingTarget = `../${mediaFileName}`;
     const relNum = drawingRels.addAndGetId(
@@ -581,66 +549,27 @@ export class ExcelWorksheet {
 
   //#region Private Methods
 
-  private async _getWsData(): Promise<ExcelXmlWorksheet> {
-    return (await this._zipCache.get(`xl/worksheets/${this._targetFileName}`)) as ExcelXmlWorksheet;
+  private async _getWsData(): Promise<IWorksheetModel> {
+    return (await this._zipCache.get(`xl/worksheets/${this._targetFileName}`)) as IWorksheetModel;
   }
 
-  private async _getWbData(): Promise<ExcelXmlWorkbook> {
-    return (await this._zipCache.get("xl/workbook.xml")) as ExcelXmlWorkbook;
+  private async _getWbData(): Promise<IWorkbookModel> {
+    return (await this._zipCache.get("xl/workbook.xml")) as IWorkbookModel;
   }
 
-  private async _ensureSsData(): Promise<ExcelXmlSharedString> {
-    let ssData = (await this._zipCache.get("xl/sharedStrings.xml")) as
-      | ExcelXmlSharedString
-      | undefined;
-    if (ssData == null) {
-      ssData = new ExcelXmlSharedStringClass();
-      this._zipCache.set("xl/sharedStrings.xml", ssData);
-
-      const typeData = (await this._zipCache.get("[Content_Types].xml")) as ExcelXmlContentType;
-      typeData.add(
-        "/xl/sharedStrings.xml",
-        "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml",
-      );
-
-      const wbRelData = (await this._zipCache.get(
-        "xl/_rels/workbook.xml.rels",
-      )) as ExcelXmlRelationship;
-      wbRelData.add(
-        "sharedStrings.xml",
-        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings",
-      );
-    }
-    return ssData;
+  private async _ensureSsData(): Promise<ISharedStringModel> {
+    return this._zipCache.ensureSharedStrings();
   }
 
-  private async _ensureStyleData(): Promise<ExcelXmlStyle> {
-    let styleData = (await this._zipCache.get("xl/styles.xml")) as ExcelXmlStyle | undefined;
-    if (styleData == null) {
-      styleData = new ExcelXmlStyleClass();
-      this._zipCache.set("xl/styles.xml", styleData);
-
-      const typeData = (await this._zipCache.get("[Content_Types].xml")) as ExcelXmlContentType;
-      typeData.add(
-        "/xl/styles.xml",
-        "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml",
-      );
-
-      const wbRelData = (await this._zipCache.get(
-        "xl/_rels/workbook.xml.rels",
-      )) as ExcelXmlRelationship;
-      wbRelData.add(
-        "styles.xml",
-        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles",
-      );
-    }
-    return styleData;
+  private async _ensureStyleData(): Promise<IStyleModel> {
+    // styles 파트 content-type·rel 은 포맷(xlsx/.xml, xlsb/.bin)에 맞춰야 하므로 zipCache 에 위임.
+    return this._zipCache.ensureStyles();
   }
 
   private _setCellValueSync(
-    wsData: ExcelXmlWorksheet,
-    ssData: ExcelXmlSharedString,
-    styleData: ExcelXmlStyle,
+    wsData: IWorksheetModel,
+    ssData: ISharedStringModel,
+    styleData: IStyleModel,
     addr: ExcelAddressPoint,
     val: ExcelValueType,
   ): void {

package/src/excel-wrapper.ts

@@ -97,16 +97,6 @@ export class ExcelWrapper<TSchema extends z.ZodObject<z.ZodRawShape>> {
    * @remarks
    * 반환된 워크북의 리소스 관리는 호출자의 책임이다.
    * 사용 후 `close()`를 호출해야 한다.
-   *
-   * @example
-   * ```typescript
-   * const wb = await wrapper.write("Sheet1", records);
-   * try {
-   *   const bytes = await wb.toBytes();
-   * } finally {
-   *   await wb.close();
-   * }
-   * ```
    */
   async write(
     wsName: string,

package/src/models/excel-format.ts

@@ -0,0 +1,2 @@
+/** 워크북 컨테이너 포맷. xlsx = OOXML XML, xlsb = BIFF12 바이너리. */
+export type ExcelFormat = "xlsx" | "xlsb";

package/src/models/excel-model-factory.ts

@@ -0,0 +1,33 @@
+import type { Bytes } from "@simplysm/core-common";
+import type { ExcelFormat } from "./excel-format";
+import type { IExcelModel } from "./excel-model";
+import type { IContentTypeModel } from "./i-content-type-model";
+import type { IDrawingModel } from "./i-drawing-model";
+import type { IRelationshipModel } from "./i-relationship-model";
+import type { ISharedStringModel } from "./i-shared-string-model";
+import type { IStyleModel } from "./i-style-model";
+import type { IWorkbookModel } from "./i-workbook-model";
+import type { IWorksheetModel } from "./i-worksheet-model";
+
+/**
+ * 포맷별 파트 모델 팩토리 계약.
+ *
+ * - `createXxx()`: 빈(신규) 파트 모델 생성 — 상위 레이어의 `new XmlXxx()` 직접 생성을 대체.
+ * - `parse()`: ZIP 내부 파일 바이트를 경로 패턴에 맞는 파트 모델로 역직렬화 — `ZipCache.get` 의 분기 대체.
+ *
+ * `ZipCache` 는 워크북 포맷에 맞는 팩토리 1개를 보유하고 모든 파트 생성·복원을 위임한다.
+ */
+export interface IExcelModelFactory {
+  readonly format: ExcelFormat;
+  /** 이 파일 경로를 모델로 파싱할 파트인지(true) 원시 바이트로 둘지(false) 판정. */
+  isModelPart(filePath: string): boolean;
+  createWorkbook(): IWorkbookModel;
+  createWorksheet(): IWorksheetModel;
+  createStyle(): IStyleModel;
+  createSharedString(): ISharedStringModel;
+  createContentType(): IContentTypeModel;
+  createRelationship(): IRelationshipModel;
+  createDrawing(): IDrawingModel;
+  /** 경로 패턴 → 적절한 파트 모델로 역직렬화. 매칭 없으면 unknown(패스스루) 모델. */
+  parse(filePath: string, bytes: Bytes): IExcelModel;
+}

package/src/models/excel-model.ts

@@ -0,0 +1,12 @@
+import type { Bytes } from "@simplysm/core-common";
+
+/**
+ * Excel ZIP 파트 1개의 포맷 중립 모델 계약.
+ *
+ * 구현체(xml/biff)는 자신이 담당하는 파트를 메모리 모델로 들고 있다가, 직렬화 시점에
+ * 자기 포맷의 바이트로 변환한다. 직렬화 직전 정규화(OOXML 자식 순서 재배치 등)는 구현 내부에서 수행한다.
+ */
+export interface IExcelModel {
+  /** 이 파트를 자기 포맷의 바이트로 직렬화. */
+  serialize(): Bytes;
+}

package/src/models/i-content-type-model.ts

@@ -0,0 +1,7 @@
+import type { IExcelModel } from "./excel-model";
+
+/** [Content_Types].xml 파트 모델 계약. (xlsb 도 이 파트는 XML.) */
+export interface IContentTypeModel extends IExcelModel {
+  /** 파트별 ContentType override 추가. 중복 PartName 은 무시. */
+  add(partName: string, contentType: string): this;
+}

package/src/models/i-drawing-model.ts

@@ -0,0 +1,13 @@
+import type { IExcelModel } from "./excel-model";
+
+/**
+ * xl/drawings/drawing*.xml 파트 모델 계약.
+ * xlsb 도 drawing 은 OOXML XML 을 그대로 사용하므로 단일(xml) 구현으로 충분하다.
+ */
+export interface IDrawingModel extends IExcelModel {
+  addPicture(opts: {
+    from: { r: number; c: number; rOff?: number | string; cOff?: number | string };
+    to: { r: number; c: number; rOff?: number | string; cOff?: number | string };
+    blipRelId: string;
+  }): void;
+}

package/src/models/i-relationship-model.ts

@@ -0,0 +1,13 @@
+import type { IExcelModel } from "./excel-model";
+
+/** *.rels 파트 모델 계약. (xlsb 도 이 파트는 XML.) */
+export interface IRelationshipModel extends IExcelModel {
+  getTargetByRelId(rId: number): string | undefined;
+  add(target: string, type: string): this;
+  /** 관계 추가 후 rId 숫자부 반환. */
+  addAndGetId(target: string, type: string): number;
+  /** 지정 rId 위치에 삽입하고 이후 id 를 시프트. */
+  insert(rId: number, target: string, type: string): this;
+  /** 특정 Type 의 첫 관계를 찾아 relId(`rId..`)·target 반환. addImage 의 drawing rel 탐색용. */
+  findRelByType(type: string): { relId: string; target: string } | undefined;
+}

package/src/models/i-shared-string-model.ts

@@ -0,0 +1,9 @@
+import type { IExcelModel } from "./excel-model";
+
+/** xl/sharedStrings.{xml,bin} 파트 모델 계약. 문자열 중복 제거 테이블. */
+export interface ISharedStringModel extends IExcelModel {
+  getIdByString(str: string): number | undefined;
+  getStringById(id: number): string | undefined;
+  /** 문자열 추가 후 인덱스 반환. */
+  add(str: string): number;
+}

package/src/models/i-style-model.ts

@@ -0,0 +1,18 @@
+import type { ExcelConditionalRuleStyle } from "../types";
+import type { ExcelStyle } from "./shared/excel-style";
+import type { IExcelModel } from "./excel-model";
+
+/** xl/styles.{xml,bin} 파트 모델 계약. numFmt·font·fill·border·xf·dxf 관리. */
+export interface IStyleModel extends IExcelModel {
+  /** 스타일을 등록하고 styleId(문자열 핸들) 반환. 동일 스타일은 재사용. */
+  add(style: ExcelStyle): string;
+  /** 기존 styleId 를 clone 후 일부 속성만 덮어쓴 새 스타일 등록. */
+  addWithClone(id: string, style: ExcelStyle): string;
+  /** styleId 의 스타일 역조회. */
+  get(id: string): ExcelStyle;
+  getNumFmtCode(numFmtId: string): string | undefined;
+  /** 조건부 서식 dxf 등록 후 dxfId 반환. */
+  addDxf(style: ExcelConditionalRuleStyle): string;
+  /** 워크북 전역 기본 스타일 (0번 슬롯) 설정. */
+  setDefaultStyle(style: ExcelStyle): void;
+}

package/src/models/i-workbook-model.ts

@@ -0,0 +1,17 @@
+import type { IExcelModel } from "./excel-model";
+
+/** xl/workbook.{xml,bin} 파트 모델 계약. 워크시트 목록·관계 ID 관리. */
+export interface IWorkbookModel extends IExcelModel {
+  /** 등록된 워크시트 이름 목록. */
+  readonly sheetNames: string[];
+  /** 최대 워크시트 관계 ID (rId 숫자부). 없으면 undefined. */
+  readonly lastWsRelId: number | undefined;
+  /** 새 워크시트 엔트리 추가 (이름 sanitize·relId/sheetId 자동 증가). */
+  addWorksheet(name: string): this;
+  getWsRelIdByName(name: string): number | undefined;
+  getWsRelIdByIndex(index: number): number | undefined;
+  getWorksheetNameById(id: number): string | undefined;
+  setWorksheetNameById(id: number, newName: string): void;
+  /** bookViews 기본 골격 보장 (zoom·freeze 전 선행). */
+  initializeView(): void;
+}

package/src/models/i-worksheet-model.ts

@@ -0,0 +1,40 @@
+import type { ExcelAddressPoint, ExcelAddressRangePoint, ExcelCellType } from "../types";
+import type { ICfRuleSpec } from "./shared/excel-cf-spec";
+import type { IExcelModel } from "./excel-model";
+
+/** xl/worksheets/sheet*.{xml,bin} 파트 모델 계약. 셀·병합·뷰·CF 관리. */
+export interface IWorksheetModel extends IExcelModel {
+  /** 데이터가 존재하는 셀 범위 (s: 좌상단, e: 우하단). */
+  readonly range: ExcelAddressRangePoint;
+
+  getCellStyleId(addr: ExcelAddressPoint): string | undefined;
+  setCellStyleId(addr: ExcelAddressPoint, styleId: string | undefined): void;
+  getCellType(addr: ExcelAddressPoint): ExcelCellType | undefined;
+  setCellType(addr: ExcelAddressPoint, type: ExcelCellType | undefined): void;
+  getCellVal(addr: ExcelAddressPoint): string | undefined;
+  setCellVal(addr: ExcelAddressPoint, val: string | undefined): void;
+  getCellFormula(addr: ExcelAddressPoint): string | undefined;
+  setCellFormula(addr: ExcelAddressPoint, val: string | undefined): void;
+  deleteCell(addr: ExcelAddressPoint): void;
+
+  setMergeCells(startAddr: ExcelAddressPoint, endAddr: ExcelAddressPoint): void;
+  getMergeCells(): ExcelAddressRangePoint[];
+  shiftMergeCells(fromRow: number, delta: number): void;
+
+  copyRow(sourceR: number, targetR: number, options?: { skipMerge?: boolean }): void;
+  copyCell(sourceAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): void;
+
+  addConditionalFormatting(
+    sqref: string,
+    rules: { dxfId: string; cfRule: ICfRuleSpec }[],
+  ): void;
+
+  setTabColor(rgb: string): void;
+  setZoom(percent: number): void;
+  freezeAt(point: { r?: number; c?: number }): void;
+  setAutoFilter(range: ExcelAddressRangePoint): void;
+  setColWidth(colIndex: string, width: string): void;
+
+  /** 워크시트에 drawing 파트 참조(rId) 연결. addImage 가 .data 직접 조작 대신 호출. */
+  setDrawingRelId(relId: string): void;
+}

package/src/models/shared/excel-cf-spec.ts

@@ -0,0 +1,24 @@
+/**
+ * 포맷 중립 조건부 서식 규칙 spec.
+ *
+ * 사용자 표면 `ExcelConditionalRule` 을 워크시트 모델이 소비하기 좋은 형태로 정규화한 것.
+ * xml 은 `<cfRule>` 엘리먼트로, biff 는 CF 레코드군으로 직렬화한다.
+ */
+export interface ICfRuleSpec {
+  type: "cellIs" | "containsText" | "notContainsText" | "beginsWith" | "endsWith" | "expression";
+  operator?:
+    | "lessThan"
+    | "lessThanOrEqual"
+    | "equal"
+    | "notEqual"
+    | "greaterThanOrEqual"
+    | "greaterThan"
+    | "between"
+    | "notBetween"
+    | "containsText"
+    | "notContains"
+    | "beginsWith"
+    | "endsWith";
+  text?: string;
+  formula: string[];
+}

package/src/models/shared/excel-style.ts

@@ -0,0 +1,65 @@
+import type {
+  ExcelBorderPosition,
+  ExcelFont,
+  ExcelHorizontalAlign,
+  ExcelStyleOptions,
+  ExcelVerticalAlign,
+} from "../../types";
+import { ExcelUtils } from "../../utils/excel-utils";
+
+/**
+ * 포맷 중립 셀 스타일. 사용자 표면 `ExcelStyleOptions` 를 내부 표현으로 정규화한 것으로,
+ * xml/biff 두 구현의 스타일 모델이 공유한다.
+ */
+export interface ExcelStyle {
+  numFmtId?: string;
+  numFmtCode?: string;
+  border?: ExcelBorderPosition[];
+  background?: string;
+  verticalAlign?: ExcelVerticalAlign;
+  horizontalAlign?: ExcelHorizontalAlign;
+  font?: ExcelFont;
+}
+
+/**
+ * `ExcelStyleOptions` (사용자 표면) → 내부 `ExcelStyle` 변환.
+ * cell.setStyle 과 wb.setDefaultStyle 이 공유한다.
+ *
+ * - background ARGB 8자리 형식 검증
+ * - numberFormatCode 가 numberFormat 보다 우선
+ * - font 는 그대로 전달 (구체 검증은 스타일 모델 내부에서 수행)
+ */
+export function convertExcelStyleOptions(opts: ExcelStyleOptions): ExcelStyle {
+  const style: ExcelStyle = {};
+
+  if (opts.background != null) {
+    if (!/^[0-9A-F]{8}$/i.test(opts.background)) {
+      throw new Error("잘못된 색상 형식입니다. (형식: 00000000: alpha(반전)+rgb)");
+    }
+    style.background = opts.background;
+  }
+
+  if (opts.border != null) {
+    style.border = opts.border;
+  }
+
+  if (opts.horizontalAlign != null) {
+    style.horizontalAlign = opts.horizontalAlign;
+  }
+
+  if (opts.verticalAlign != null) {
+    style.verticalAlign = opts.verticalAlign;
+  }
+
+  if (opts.numberFormatCode != null) {
+    style.numFmtCode = opts.numberFormatCode;
+  } else if (opts.numberFormat != null) {
+    style.numFmtId = ExcelUtils.convertNumFmtNameToId(opts.numberFormat).toString();
+  }
+
+  if (opts.font != null) {
+    style.font = opts.font;
+  }
+
+  return style;
+}

package/src/types.ts

@@ -475,19 +475,6 @@ export interface ExcelFont {
 
 /**
  * 셀 스타일 옵션
- * @example
- * ```typescript
- * await cell.setStyle({
- *   background: "00FF0000",  // 빨강
- *   border: ["left", "right", "top", "bottom"],
- *   horizontalAlign: "center",
- *   verticalAlign: "center",
- *   numberFormat: "number",
- * });
- *
- * // 임의의 Excel formatCode 지정
- * await cell.setStyle({ numberFormatCode: "0.000000" });
- * ```
  */
 export interface ExcelStyleOptions {
   /** 배경색 (ARGB 형식, 예: "00FF0000") */

package/src/utils/excel-style-data.ts

@@ -1,31 +1,10 @@
 import type { ZipCache } from "./zip-cache";
-import { ExcelXmlContentType } from "../xml/excel-xml-content-type";
-import { ExcelXmlRelationship } from "../xml/excel-xml-relationship";
-import { ExcelXmlStyle } from "../xml/excel-xml-style";
+import type { IStyleModel } from "../models/i-style-model";
 
 /**
- * `xl/styles.xml` 을 가져오거나, 없으면 새로 만들어 ZipCache 에 등록한다.
- * Content_Types / workbook.xml.rels 에도 styles.xml 항목을 추가한다.
- *
+ * `xl/styles` 파트를 가져오거나 없으면 생성·등록한다 (포맷별 처리는 ZipCache 에 위임).
  * `ExcelCell.setStyle` 과 `ExcelWorkbook.setDefaultStyle` 양쪽이 공유한다.
  */
-export async function getOrCreateStyleData(zipCache: ZipCache): Promise<ExcelXmlStyle> {
-  let styleData = (await zipCache.get("xl/styles.xml")) as ExcelXmlStyle | undefined;
-  if (styleData == null) {
-    styleData = new ExcelXmlStyle();
-    zipCache.set("xl/styles.xml", styleData);
-
-    const typeData = (await zipCache.get("[Content_Types].xml")) as ExcelXmlContentType;
-    typeData.add(
-      "/xl/styles.xml",
-      "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml",
-    );
-
-    const wbRelData = (await zipCache.get("xl/_rels/workbook.xml.rels")) as ExcelXmlRelationship;
-    wbRelData.add(
-      "styles.xml",
-      "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles",
-    );
-  }
-  return styleData;
+export async function getOrCreateStyleData(zipCache: ZipCache): Promise<IStyleModel> {
+  return zipCache.ensureStyles();
 }