kordoc 2.2.3 → 2.2.4

package/dist/index.d.cts

@@ -227,12 +227,70 @@ declare function diffBlocks(blocksA: IRBlock[], blocksB: IRBlock[]): DiffResult;
 
 /** 양식(서식) 필드 인식 — 테이블 기반 label-value 패턴 매칭 */
 
+/** 라벨처럼 보이는 셀인지 판별 */
+declare function isLabelCell(text: string): boolean;
 /**
  * IRBlock[]에서 양식 필드를 인식하여 추출.
  * 테이블의 label-value 패턴을 감지.
  */
 declare function extractFormFields(blocks: IRBlock[]): FormResult;
 
+/** 양식 서식 필드 값 채우기 — IRBlock[] 기반 in-place 교체 */
+
+/** 필드 채우기 결과 */
+interface FillResult {
+    /** 값이 교체된 IRBlock[] */
+    blocks: IRBlock[];
+    /** 실제 채워진 필드 목록 */
+    filled: FormField[];
+    /** 매칭 실패한 라벨 (입력에는 있지만 서식에서 못 찾은 것) */
+    unmatched: string[];
+}
+/**
+ * IRBlock[]에서 양식 필드를 찾아 값을 교체.
+ *
+ * @param blocks 원본 IRBlock[] (변경하지 않음 — deep clone)
+ * @param values 채울 값 맵 (라벨 → 새 값). 라벨은 접두사 매칭 지원.
+ * @returns FillResult
+ *
+ * @example
+ * ```ts
+ * const result = await parse("신청서.hwp")
+ * if (!result.success) throw new Error(result.error)
+ * const { blocks, filled } = fillFormFields(result.blocks, {
+ *   "성명": "홍길동",
+ *   "전화번호": "010-1234-5678",
+ *   "주소": "서울시 강남구",
+ * })
+ * ```
+ */
+declare function fillFormFields(blocks: IRBlock[], values: Record<string, string>): FillResult;
+
+/**
+ * HWPX 원본 서식 유지 채우기 — ZIP 내 section XML 직접 수정
+ *
+ * IRBlock 중간 표현을 거치지 않고, 원본 HWPX ZIP의 section XML에서
+ * 테이블 셀 텍스트(<hp:t>)만 교체하여 모든 스타일을 보존합니다.
+ */
+
+/** 채우기 결과 */
+interface HwpxFillResult {
+    /** 채워진 HWPX 바이너리 */
+    buffer: ArrayBuffer;
+    /** 실제 채워진 필드 목록 */
+    filled: FormField[];
+    /** 매칭 실패한 라벨 */
+    unmatched: string[];
+}
+/**
+ * HWPX 원본을 직접 수정하여 서식 필드를 채움 — 스타일 100% 보존.
+ *
+ * @param hwpxBuffer 원본 HWPX 파일 버퍼
+ * @param values 채울 값 맵 (라벨 → 값)
+ * @returns HwpxFillResult
+ */
+declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, string>): Promise<HwpxFillResult>;
+
 /**
  * Markdown → HWPX 역변환
  *
@@ -270,12 +328,6 @@ declare function blocksToMarkdown(blocks: IRBlock[]): string;
 /** kordoc 공용 유틸리티 */
 declare const VERSION: string;
 
-/**
- * kordoc — 모두 파싱해버리겠다
- *
- * HWP, HWPX, PDF → Markdown 변환 통합 라이브러리
- */
-
 /**
  * 파일 버퍼를 자동 감지하여 Markdown으로 변환
  *
@@ -299,5 +351,43 @@ declare function parsePdf(buffer: ArrayBuffer, options?: ParseOptions): Promise<
 declare function parseXlsx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** DOCX 파일을 Markdown으로 변환 */
 declare function parseDocx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
+/**
+ * 서식 채우기 출력 포맷
+ * - "markdown": 마크다운 텍스트
+ * - "hwpx": 새로 생성한 HWPX (스타일 초기화)
+ * - "hwpx-preserve": 원본 HWPX ZIP 직접 수정 (스타일 100% 보존, HWPX 입력만 가능)
+ */
+type FillOutputFormat = "markdown" | "hwpx" | "hwpx-preserve";
+/** 서식 채우기 결과 */
+interface FillFormOutput {
+    /** 채워진 문서 (markdown: string, hwpx/hwpx-preserve: ArrayBuffer) */
+    output: string | ArrayBuffer;
+    /** 출력 포맷 */
+    format: FillOutputFormat;
+    /** 채우기 상세 — filled 필드 목록 + unmatched 라벨 */
+    fill: {
+        filled: FormField[];
+        unmatched: string[];
+    };
+}
+/**
+ * 서식 문서를 파싱하여 필드를 채우고, 원하는 포맷으로 출력.
+ *
+ * - "hwpx-preserve": HWPX 입력 → 원본 ZIP XML 직접 수정 (테두리/폰트/병합 등 100% 보존)
+ * - "hwpx": 아무 포맷 → IRBlock → Markdown → HWPX 생성 (스타일 초기화됨)
+ * - "markdown": 아무 포맷 → IRBlock → Markdown
+ *
+ * @example
+ * ```ts
+ * // HWPX 원본 스타일 보존 채우기
+ * const result = await fillForm("신청서.hwpx", { "성명": "홍길동" }, "hwpx-preserve")
+ * writeFileSync("결과.hwpx", Buffer.from(result.output as ArrayBuffer))
+ *
+ * // 아무 포맷 → 마크다운 채우기
+ * const result = await fillForm("신청서.hwp", { "성명": "홍길동" })
+ * console.log(result.output)  // 채워진 마크다운
+ * ```
+ */
+declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, string>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FormField, type FormResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, detectFormat, detectZipFormat, diffBlocks, extractFormFields, isHwpxFile, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx };
+export { type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FormField, type FormResult, type HwpxFillResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, detectFormat, detectZipFormat, diffBlocks, extractFormFields, fillForm, fillFormFields, fillHwpx, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx };

package/dist/index.d.ts

@@ -227,12 +227,70 @@ declare function diffBlocks(blocksA: IRBlock[], blocksB: IRBlock[]): DiffResult;
 
 /** 양식(서식) 필드 인식 — 테이블 기반 label-value 패턴 매칭 */
 
+/** 라벨처럼 보이는 셀인지 판별 */
+declare function isLabelCell(text: string): boolean;
 /**
  * IRBlock[]에서 양식 필드를 인식하여 추출.
  * 테이블의 label-value 패턴을 감지.
  */
 declare function extractFormFields(blocks: IRBlock[]): FormResult;
 
+/** 양식 서식 필드 값 채우기 — IRBlock[] 기반 in-place 교체 */
+
+/** 필드 채우기 결과 */
+interface FillResult {
+    /** 값이 교체된 IRBlock[] */
+    blocks: IRBlock[];
+    /** 실제 채워진 필드 목록 */
+    filled: FormField[];
+    /** 매칭 실패한 라벨 (입력에는 있지만 서식에서 못 찾은 것) */
+    unmatched: string[];
+}
+/**
+ * IRBlock[]에서 양식 필드를 찾아 값을 교체.
+ *
+ * @param blocks 원본 IRBlock[] (변경하지 않음 — deep clone)
+ * @param values 채울 값 맵 (라벨 → 새 값). 라벨은 접두사 매칭 지원.
+ * @returns FillResult
+ *
+ * @example
+ * ```ts
+ * const result = await parse("신청서.hwp")
+ * if (!result.success) throw new Error(result.error)
+ * const { blocks, filled } = fillFormFields(result.blocks, {
+ *   "성명": "홍길동",
+ *   "전화번호": "010-1234-5678",
+ *   "주소": "서울시 강남구",
+ * })
+ * ```
+ */
+declare function fillFormFields(blocks: IRBlock[], values: Record<string, string>): FillResult;
+
+/**
+ * HWPX 원본 서식 유지 채우기 — ZIP 내 section XML 직접 수정
+ *
+ * IRBlock 중간 표현을 거치지 않고, 원본 HWPX ZIP의 section XML에서
+ * 테이블 셀 텍스트(<hp:t>)만 교체하여 모든 스타일을 보존합니다.
+ */
+
+/** 채우기 결과 */
+interface HwpxFillResult {
+    /** 채워진 HWPX 바이너리 */
+    buffer: ArrayBuffer;
+    /** 실제 채워진 필드 목록 */
+    filled: FormField[];
+    /** 매칭 실패한 라벨 */
+    unmatched: string[];
+}
+/**
+ * HWPX 원본을 직접 수정하여 서식 필드를 채움 — 스타일 100% 보존.
+ *
+ * @param hwpxBuffer 원본 HWPX 파일 버퍼
+ * @param values 채울 값 맵 (라벨 → 값)
+ * @returns HwpxFillResult
+ */
+declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, string>): Promise<HwpxFillResult>;
+
 /**
  * Markdown → HWPX 역변환
  *
@@ -270,12 +328,6 @@ declare function blocksToMarkdown(blocks: IRBlock[]): string;
 /** kordoc 공용 유틸리티 */
 declare const VERSION: string;
 
-/**
- * kordoc — 모두 파싱해버리겠다
- *
- * HWP, HWPX, PDF → Markdown 변환 통합 라이브러리
- */
-
 /**
  * 파일 버퍼를 자동 감지하여 Markdown으로 변환
  *
@@ -299,5 +351,43 @@ declare function parsePdf(buffer: ArrayBuffer, options?: ParseOptions): Promise<
 declare function parseXlsx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** DOCX 파일을 Markdown으로 변환 */
 declare function parseDocx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
+/**
+ * 서식 채우기 출력 포맷
+ * - "markdown": 마크다운 텍스트
+ * - "hwpx": 새로 생성한 HWPX (스타일 초기화)
+ * - "hwpx-preserve": 원본 HWPX ZIP 직접 수정 (스타일 100% 보존, HWPX 입력만 가능)
+ */
+type FillOutputFormat = "markdown" | "hwpx" | "hwpx-preserve";
+/** 서식 채우기 결과 */
+interface FillFormOutput {
+    /** 채워진 문서 (markdown: string, hwpx/hwpx-preserve: ArrayBuffer) */
+    output: string | ArrayBuffer;
+    /** 출력 포맷 */
+    format: FillOutputFormat;
+    /** 채우기 상세 — filled 필드 목록 + unmatched 라벨 */
+    fill: {
+        filled: FormField[];
+        unmatched: string[];
+    };
+}
+/**
+ * 서식 문서를 파싱하여 필드를 채우고, 원하는 포맷으로 출력.
+ *
+ * - "hwpx-preserve": HWPX 입력 → 원본 ZIP XML 직접 수정 (테두리/폰트/병합 등 100% 보존)
+ * - "hwpx": 아무 포맷 → IRBlock → Markdown → HWPX 생성 (스타일 초기화됨)
+ * - "markdown": 아무 포맷 → IRBlock → Markdown
+ *
+ * @example
+ * ```ts
+ * // HWPX 원본 스타일 보존 채우기
+ * const result = await fillForm("신청서.hwpx", { "성명": "홍길동" }, "hwpx-preserve")
+ * writeFileSync("결과.hwpx", Buffer.from(result.output as ArrayBuffer))
+ *
+ * // 아무 포맷 → 마크다운 채우기
+ * const result = await fillForm("신청서.hwp", { "성명": "홍길동" })
+ * console.log(result.output)  // 채워진 마크다운
+ * ```
+ */
+declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, string>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FormField, type FormResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, detectFormat, detectZipFormat, diffBlocks, extractFormFields, isHwpxFile, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx };
+export { type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FormField, type FormResult, type HwpxFillResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, detectFormat, detectZipFormat, diffBlocks, extractFormFields, fillForm, fillFormFields, fillHwpx, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx };