hwpkit-dev 0.0.1 → 0.0.3

package/ .npmignore

@@ -1,5 +1,4 @@
 node_modules
-dist
 *.hml
 *.hml.md
 *.hwpx
@@ -9,3 +8,7 @@ dist
 tests
 data
 playground
+CLAUDE.*
+.c
+Tester.so.c
+*.hwp

package/README.md

@@ -26,10 +26,11 @@
 | 입력 \ 출력 | HWPX | DOCX | Markdown |
 |------------|:----:|:----:|:--------:|
 | **HWPX**   | -    | O    | O        |
-| **HWP**    | O    | O    | O        |
+| **HWP**    | □    | O    | O        |
 | **DOCX**   | O    | -    | O        |
-| **Markdown** | O  | O    | -        |
+| **Markdown** | □  | □    | -        |
 
+> 한글 소프트웨어서는 작동이 안됨 (수정중)
 ---
 
 ## 설치
@@ -113,6 +114,42 @@ const doc = buildRoot({ title: '제목' }, [
 ]);
 ```
 
+### 스타일 적용
+
+```typescript
+// 텍스트 스타일
+buildSpan('스타일 적용 텍스트', {
+  font: 'Malgun Gothic',  // 글꼴
+  pt: 14,                 // 글자 크기 (pt)
+  b: true,                // 볼드
+  i: true,                // 이탤릭
+  u: true,                // 밑줄
+  s: true,                // 취소선
+  color: 'FF0000',        // 글색 (hex, BGR)
+  bg: 'FFFF00'           // 형광펜 (hex, BGR)
+});
+
+// 표 정렬 및 선 스타일
+buildGrid(rows, {
+  align: 'center',        // 표 정렬: 'left' | 'center' | 'right'
+  defaultStroke: {        // 기본 선 스타일
+    kind: 'solid',        // 선 종류: 'solid' | 'double' | 'dash' | 'dot'
+    pt: 1,                // 선 굵기 (pt)
+    color: '000000'       // 선 색상 (hex, BGR)
+  },
+  colWidths: [100, 100]   // 열 너비 (pt)
+});
+
+// 개별 셀의 선 스타일
+buildCell(content, {
+  top: { kind: 'double', pt: 2, color: '0000FF' },  // 상단 선
+  bot: { kind: 'dash', pt: 1.5, color: 'FF0000' },  // 하단 선
+  left: { kind: 'dot', pt: 1, color: '00FF00' },    // 좌측 선
+  right: { kind: 'solid', pt: 3, color: 'FFFF00' }, // 우측 선
+  bg: 'FFFFFF'                                        // 셀 배경색
+});
+```
+
 ### 트리 순회
 
 ```typescript

package/dist/index.d.mts

@@ -1,7 +1,27 @@
 type Align = 'left' | 'center' | 'right' | 'justify';
+type ImgWrap = 'inline' | 'square' | 'tight' | 'through' | 'none' | 'behind' | 'front' | 'topAndBottom';
+type ImgHorzAlign = 'left' | 'center' | 'right';
+type ImgVertAlign = 'top' | 'center' | 'bottom';
+type ImgHorzRelTo = 'margin' | 'column' | 'page' | 'para';
+type ImgVertRelTo = 'margin' | 'line' | 'page' | 'para';
+interface ImgLayout {
+    wrap: ImgWrap;
+    horzAlign?: ImgHorzAlign;
+    vertAlign?: ImgVertAlign;
+    horzRelTo?: ImgHorzRelTo;
+    vertRelTo?: ImgVertRelTo;
+    xPt?: number;
+    yPt?: number;
+    distT?: number;
+    distB?: number;
+    distL?: number;
+    distR?: number;
+    behindDoc?: boolean;
+    zOrder?: number;
+}
 type VAlign = 'top' | 'mid' | 'bot';
 type Heading = 1 | 2 | 3 | 4 | 5 | 6;
-type StrokeKind = 'solid' | 'dash' | 'dot' | 'double' | 'none';
+type StrokeKind = 'solid' | 'dash' | 'dot' | 'double' | 'none' | 'dashDot' | 'dashDotDot' | 'wave';
 interface TextProps {
     b?: boolean;
     i?: boolean;
@@ -17,10 +37,15 @@ interface TextProps {
 interface ParaProps {
     align?: Align;
     heading?: Heading;
+    styleId?: string;
     indentPt?: number;
+    indentRightPt?: number;
+    firstLineIndentPt?: number;
+    leftMargin?: number;
     spaceBefore?: number;
     spaceAfter?: number;
     lineHeight?: number;
+    lineHeightFixed?: number;
     listLv?: number;
     listOrd?: boolean;
     listMark?: string;
@@ -37,6 +62,10 @@ interface CellProps {
     right?: Stroke;
     bg?: string;
     padPt?: number;
+    padT?: number;
+    padB?: number;
+    padL?: number;
+    padR?: number;
     align?: Align;
     va?: VAlign;
     isHeader?: boolean;
@@ -55,6 +84,7 @@ interface GridProps {
     defaultStroke?: Stroke;
     look?: TableLook;
     headerRow?: boolean;
+    align?: Align;
 }
 interface PageDims {
     wPt: number;
@@ -64,6 +94,8 @@ interface PageDims {
     ml: number;
     mr: number;
     orient?: 'portrait' | 'landscape';
+    headerPt?: number;
+    footerPt?: number;
 }
 interface DocMeta {
     title?: string;
@@ -73,8 +105,17 @@ interface DocMeta {
     keywords?: string;
     created?: string;
     modified?: string;
+    zoom?: number;
+    viewMode?: string;
 }
 declare const A4: PageDims;
+declare const A4_LANDSCAPE: PageDims;
+/**
+ * orient === 'landscape'일 때 wPt < hPt이면 swap,
+ * orient === 'portrait'일 때 wPt > hPt이면 swap하여
+ * 방향과 치수가 항상 일치하도록 정규화합니다.
+ */
+declare function normalizeDims(dims: PageDims): PageDims;
 declare const DEFAULT_STROKE: Stroke;
 
 type BlockTag = 'root' | 'sheet' | 'para' | 'span' | 'txt' | 'img' | 'link' | 'grid' | 'row' | 'cell' | 'br' | 'pb' | 'pagenum';
@@ -99,6 +140,7 @@ interface ImgNode {
     w: number;
     h: number;
     alt?: string;
+    layout?: ImgLayout;
 }
 interface SpanNode {
     tag: 'span';
@@ -113,18 +155,19 @@ interface LinkNode {
 interface ParaNode {
     tag: 'para';
     props: ParaProps;
-    kids: (SpanNode | ImgNode | LinkNode)[];
+    kids: (SpanNode | ImgNode | LinkNode | GridNode)[];
 }
 interface CellNode {
     tag: 'cell';
     cs: number;
     rs: number;
     props: CellProps;
-    kids: ParaNode[];
+    kids: (ParaNode | GridNode)[];
 }
 interface RowNode {
     tag: 'row';
     kids: CellNode[];
+    heightPt?: number;
 }
 interface GridNode {
     tag: 'grid';
@@ -136,8 +179,16 @@ interface SheetNode {
     tag: 'sheet';
     dims: PageDims;
     kids: ContentNode[];
-    header?: ParaNode[];
-    footer?: ParaNode[];
+    headers?: {
+        default?: ParaNode[];
+        first?: ParaNode[];
+        even?: ParaNode[];
+    };
+    footers?: {
+        default?: ParaNode[];
+        first?: ParaNode[];
+        even?: ParaNode[];
+    };
 }
 interface DocRoot {
     tag: 'root';
@@ -160,14 +211,19 @@ interface Fail {
 declare function succeed<T>(data: T, warns?: string[]): Ok<T>;
 declare function fail(error: string, warns?: string[]): Fail;
 
-interface Decoder {
+interface EncoderOptions {
+    [key: string]: any;
+}
+interface Encoder {
     readonly format: string;
-    decode(data: Uint8Array): Promise<Outcome<DocRoot>>;
+    readonly aliases?: string[];
+    encode(doc: DocRoot, options?: EncoderOptions): Promise<Outcome<Uint8Array>>;
 }
 
-interface Encoder {
+interface Decoder {
     readonly format: string;
-    encode(doc: DocRoot): Promise<Outcome<Uint8Array>>;
+    readonly aliases?: string[];
+    decode(data: Uint8Array): Promise<Outcome<DocRoot>>;
 }
 
 declare class Pipeline {
@@ -179,7 +235,7 @@ declare class Pipeline {
     /** File/Blob 비동기 입력 */
     static openAsync(input: File | Blob | Uint8Array | string, fmt?: string): Promise<Pipeline>;
     /** 목표 포맷으로 변환 */
-    to(targetFmt: string): Promise<Outcome<Uint8Array>>;
+    to(targetFmt: string, options?: EncoderOptions): Promise<Outcome<Uint8Array>>;
     /** DocRoot만 추출 (인코딩 없이) */
     inspect(): Promise<Outcome<DocRoot>>;
 }
@@ -198,16 +254,18 @@ declare const registry: FormatRegistry;
 
 declare function buildRoot(meta?: DocMeta, kids?: SheetNode[]): DocRoot;
 declare function buildSheet(kids?: ContentNode[], dims?: PageDims, opts?: {
-    header?: ParaNode[];
-    footer?: ParaNode[];
+    headers?: SheetNode["headers"];
+    footers?: SheetNode["footers"];
 }): SheetNode;
 declare function buildPageNum(format?: PageNumNode['format']): PageNumNode;
+declare function buildBr(): BrNode;
+declare function buildPb(): PbNode;
 declare function buildPara(kids?: ParaNode['kids'], props?: ParaProps): ParaNode;
 declare function buildSpan(content: string, props?: TextProps): SpanNode;
-declare function buildImg(b64: string, mime: ImgNode['mime'], w: number, h: number, alt?: string): ImgNode;
+declare function buildImg(b64: string, mime: ImgNode['mime'], w: number, h: number, alt?: string, layout?: ImgLayout): ImgNode;
 declare function buildGrid(kids: RowNode[], props?: GridProps): GridNode;
-declare function buildRow(kids: CellNode[]): RowNode;
-declare function buildCell(kids: ParaNode[], opts?: {
+declare function buildRow(kids: CellNode[], heightPt?: number): RowNode;
+declare function buildCell(kids: (ParaNode | GridNode)[], opts?: {
     cs?: number;
     rs?: number;
     props?: CellProps;
@@ -310,4 +368,4 @@ declare const TextKit: {
     base64Decode(b64: string): Uint8Array;
 };
 
-export { A4, type Align, type AnyNode, ArchiveKit, BinaryKit, type BlockTag, type BrNode, type CellNode, type CellProps, type ContentNode, DEFAULT_STROKE, type Decoder, type DocMeta, type DocRoot, type Encoder, type Fail, type GridNode, type GridProps, type Heading, type ImgNode, type LinkNode, Metric, type Ok, type Outcome, type PageDims, type PageNumNode, type ParaNode, type ParaProps, type PbNode, Pipeline, type RowNode, type SheetNode, ShieldedParser, type SpanNode, type Stroke, type StrokeKind, type TableLook, TextKit, type TextProps, TreeWalker, type TxtNode, type VAlign, XmlKit, buildCell, buildGrid, buildImg, buildPageNum, buildPara, buildRoot, buildRow, buildSheet, buildSpan, countNodes, fail, registry, safeAlign, safeFont, safeFontToKr, safeHex, safeStrokeDocx, safeStrokeHwpx, succeed, validateRoot, walkNode };
+export { A4, A4_LANDSCAPE, type Align, type AnyNode, ArchiveKit, BinaryKit, type BlockTag, type BrNode, type CellNode, type CellProps, type ContentNode, DEFAULT_STROKE, type Decoder, type DocMeta, type DocRoot, type Encoder, type Fail, type GridNode, type GridProps, type Heading, type ImgNode, type LinkNode, Metric, type Ok, type Outcome, type PageDims, type PageNumNode, type ParaNode, type ParaProps, type PbNode, Pipeline, type RowNode, type SheetNode, ShieldedParser, type SpanNode, type Stroke, type StrokeKind, type TableLook, TextKit, type TextProps, TreeWalker, type TxtNode, type VAlign, XmlKit, buildBr, buildCell, buildGrid, buildImg, buildPageNum, buildPara, buildPb, buildRoot, buildRow, buildSheet, buildSpan, countNodes, fail, normalizeDims, registry, safeAlign, safeFont, safeFontToKr, safeHex, safeStrokeDocx, safeStrokeHwpx, succeed, validateRoot, walkNode };

package/dist/index.d.ts

@@ -1,7 +1,27 @@
 type Align = 'left' | 'center' | 'right' | 'justify';
+type ImgWrap = 'inline' | 'square' | 'tight' | 'through' | 'none' | 'behind' | 'front' | 'topAndBottom';
+type ImgHorzAlign = 'left' | 'center' | 'right';
+type ImgVertAlign = 'top' | 'center' | 'bottom';
+type ImgHorzRelTo = 'margin' | 'column' | 'page' | 'para';
+type ImgVertRelTo = 'margin' | 'line' | 'page' | 'para';
+interface ImgLayout {
+    wrap: ImgWrap;
+    horzAlign?: ImgHorzAlign;
+    vertAlign?: ImgVertAlign;
+    horzRelTo?: ImgHorzRelTo;
+    vertRelTo?: ImgVertRelTo;
+    xPt?: number;
+    yPt?: number;
+    distT?: number;
+    distB?: number;
+    distL?: number;
+    distR?: number;
+    behindDoc?: boolean;
+    zOrder?: number;
+}
 type VAlign = 'top' | 'mid' | 'bot';
 type Heading = 1 | 2 | 3 | 4 | 5 | 6;
-type StrokeKind = 'solid' | 'dash' | 'dot' | 'double' | 'none';
+type StrokeKind = 'solid' | 'dash' | 'dot' | 'double' | 'none' | 'dashDot' | 'dashDotDot' | 'wave';
 interface TextProps {
     b?: boolean;
     i?: boolean;
@@ -17,10 +37,15 @@ interface TextProps {
 interface ParaProps {
     align?: Align;
     heading?: Heading;
+    styleId?: string;
     indentPt?: number;
+    indentRightPt?: number;
+    firstLineIndentPt?: number;
+    leftMargin?: number;
     spaceBefore?: number;
     spaceAfter?: number;
     lineHeight?: number;
+    lineHeightFixed?: number;
     listLv?: number;
     listOrd?: boolean;
     listMark?: string;
@@ -37,6 +62,10 @@ interface CellProps {
     right?: Stroke;
     bg?: string;
     padPt?: number;
+    padT?: number;
+    padB?: number;
+    padL?: number;
+    padR?: number;
     align?: Align;
     va?: VAlign;
     isHeader?: boolean;
@@ -55,6 +84,7 @@ interface GridProps {
     defaultStroke?: Stroke;
     look?: TableLook;
     headerRow?: boolean;
+    align?: Align;
 }
 interface PageDims {
     wPt: number;
@@ -64,6 +94,8 @@ interface PageDims {
     ml: number;
     mr: number;
     orient?: 'portrait' | 'landscape';
+    headerPt?: number;
+    footerPt?: number;
 }
 interface DocMeta {
     title?: string;
@@ -73,9 +105,16 @@ interface DocMeta {
     keywords?: string;
     created?: string;
     modified?: string;
+    zoom?: number;
+    viewMode?: string;
 }
 declare const A4: PageDims;
 declare const A4_LANDSCAPE: PageDims;
+/**
+ * orient === 'landscape'일 때 wPt < hPt이면 swap,
+ * orient === 'portrait'일 때 wPt > hPt이면 swap하여
+ * 방향과 치수가 항상 일치하도록 정규화합니다.
+ */
 declare function normalizeDims(dims: PageDims): PageDims;
 declare const DEFAULT_STROKE: Stroke;
 
@@ -101,6 +140,7 @@ interface ImgNode {
     w: number;
     h: number;
     alt?: string;
+    layout?: ImgLayout;
 }
 interface SpanNode {
     tag: 'span';
@@ -115,18 +155,19 @@ interface LinkNode {
 interface ParaNode {
     tag: 'para';
     props: ParaProps;
-    kids: (SpanNode | ImgNode | LinkNode)[];
+    kids: (SpanNode | ImgNode | LinkNode | GridNode)[];
 }
 interface CellNode {
     tag: 'cell';
     cs: number;
     rs: number;
     props: CellProps;
-    kids: ParaNode[];
+    kids: (ParaNode | GridNode)[];
 }
 interface RowNode {
     tag: 'row';
     kids: CellNode[];
+    heightPt?: number;
 }
 interface GridNode {
     tag: 'grid';
@@ -138,8 +179,16 @@ interface SheetNode {
     tag: 'sheet';
     dims: PageDims;
     kids: ContentNode[];
-    header?: ParaNode[];
-    footer?: ParaNode[];
+    headers?: {
+        default?: ParaNode[];
+        first?: ParaNode[];
+        even?: ParaNode[];
+    };
+    footers?: {
+        default?: ParaNode[];
+        first?: ParaNode[];
+        even?: ParaNode[];
+    };
 }
 interface DocRoot {
     tag: 'root';
@@ -162,14 +211,19 @@ interface Fail {
 declare function succeed<T>(data: T, warns?: string[]): Ok<T>;
 declare function fail(error: string, warns?: string[]): Fail;
 
-interface Decoder {
+interface EncoderOptions {
+    [key: string]: any;
+}
+interface Encoder {
     readonly format: string;
-    decode(data: Uint8Array): Promise<Outcome<DocRoot>>;
+    readonly aliases?: string[];
+    encode(doc: DocRoot, options?: EncoderOptions): Promise<Outcome<Uint8Array>>;
 }
 
-interface Encoder {
+interface Decoder {
     readonly format: string;
-    encode(doc: DocRoot): Promise<Outcome<Uint8Array>>;
+    readonly aliases?: string[];
+    decode(data: Uint8Array): Promise<Outcome<DocRoot>>;
 }
 
 declare class Pipeline {
@@ -181,7 +235,7 @@ declare class Pipeline {
     /** File/Blob 비동기 입력 */
     static openAsync(input: File | Blob | Uint8Array | string, fmt?: string): Promise<Pipeline>;
     /** 목표 포맷으로 변환 */
-    to(targetFmt: string): Promise<Outcome<Uint8Array>>;
+    to(targetFmt: string, options?: EncoderOptions): Promise<Outcome<Uint8Array>>;
     /** DocRoot만 추출 (인코딩 없이) */
     inspect(): Promise<Outcome<DocRoot>>;
 }
@@ -200,18 +254,18 @@ declare const registry: FormatRegistry;
 
 declare function buildRoot(meta?: DocMeta, kids?: SheetNode[]): DocRoot;
 declare function buildSheet(kids?: ContentNode[], dims?: PageDims, opts?: {
-    header?: ParaNode[];
-    footer?: ParaNode[];
+    headers?: SheetNode["headers"];
+    footers?: SheetNode["footers"];
 }): SheetNode;
 declare function buildPageNum(format?: PageNumNode['format']): PageNumNode;
 declare function buildBr(): BrNode;
 declare function buildPb(): PbNode;
 declare function buildPara(kids?: ParaNode['kids'], props?: ParaProps): ParaNode;
 declare function buildSpan(content: string, props?: TextProps): SpanNode;
-declare function buildImg(b64: string, mime: ImgNode['mime'], w: number, h: number, alt?: string): ImgNode;
+declare function buildImg(b64: string, mime: ImgNode['mime'], w: number, h: number, alt?: string, layout?: ImgLayout): ImgNode;
 declare function buildGrid(kids: RowNode[], props?: GridProps): GridNode;
-declare function buildRow(kids: CellNode[]): RowNode;
-declare function buildCell(kids: ParaNode[], opts?: {
+declare function buildRow(kids: CellNode[], heightPt?: number): RowNode;
+declare function buildCell(kids: (ParaNode | GridNode)[], opts?: {
     cs?: number;
     rs?: number;
     props?: CellProps;
@@ -314,4 +368,4 @@ declare const TextKit: {
     base64Decode(b64: string): Uint8Array;
 };
 
-export { A4, A4_LANDSCAPE, type Align, type AnyNode, ArchiveKit, BinaryKit, type BlockTag, type BrNode, type CellNode, type CellProps, type ContentNode, DEFAULT_STROKE, type Decoder, type DocMeta, type DocRoot, type Encoder, type Fail, type GridNode, type GridProps, type Heading, type ImgNode, type LinkNode, Metric, normalizeDims, type Ok, type Outcome, type PageDims, type PageNumNode, type ParaNode, type ParaProps, type PbNode, Pipeline, type RowNode, type SheetNode, ShieldedParser, type SpanNode, type Stroke, type StrokeKind, type TableLook, TextKit, type TextProps, TreeWalker, type TxtNode, type VAlign, XmlKit, buildBr, buildCell, buildGrid, buildImg, buildPageNum, buildPara, buildPb, buildRoot, buildRow, buildSheet, buildSpan, countNodes, fail, registry, safeAlign, safeFont, safeFontToKr, safeHex, safeStrokeDocx, safeStrokeHwpx, succeed, validateRoot, walkNode };
+export { A4, A4_LANDSCAPE, type Align, type AnyNode, ArchiveKit, BinaryKit, type BlockTag, type BrNode, type CellNode, type CellProps, type ContentNode, DEFAULT_STROKE, type Decoder, type DocMeta, type DocRoot, type Encoder, type Fail, type GridNode, type GridProps, type Heading, type ImgNode, type LinkNode, Metric, type Ok, type Outcome, type PageDims, type PageNumNode, type ParaNode, type ParaProps, type PbNode, Pipeline, type RowNode, type SheetNode, ShieldedParser, type SpanNode, type Stroke, type StrokeKind, type TableLook, TextKit, type TextProps, TreeWalker, type TxtNode, type VAlign, XmlKit, buildBr, buildCell, buildGrid, buildImg, buildPageNum, buildPara, buildPb, buildRoot, buildRow, buildSheet, buildSpan, countNodes, fail, normalizeDims, registry, safeAlign, safeFont, safeFontToKr, safeHex, safeStrokeDocx, safeStrokeHwpx, succeed, validateRoot, walkNode };