hwpx-js 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,444 @@
+interface HWPXDocument {
+    meta: DocumentMeta;
+    head: DocumentHead;
+    sections: Section[];
+    binData: BinDataItem[];
+}
+interface DocumentMeta {
+    hwpVersion: string;
+    createdAt?: string;
+    modifiedAt?: string;
+    title?: string;
+    creator?: string;
+    description?: string;
+    subject?: string;
+    keywords?: string[];
+}
+interface DocumentHead {
+    charProperties: CharProperty[];
+    paraProperties: ParaProperty[];
+    styles: Style[];
+    borderFills: BorderFill[];
+    fontFaces: FontFace[];
+    bulletProperties: BulletProperty[];
+    numberingProperties: NumberingProperty[];
+    compatibleDoc?: string;
+}
+interface FontFace {
+    lang: FontLang;
+    fontName: string;
+    fontType?: 'ttf' | 'hps' | 'unknown';
+    substFont?: string;
+}
+type FontLang = 'HANGUL' | 'LATIN' | 'HANJA' | 'JAPANESE' | 'OTHER' | 'SYMBOL' | 'USER';
+interface CharProperty {
+    id: number;
+    height: number;
+    textColor: number;
+    shadeColor?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: UnderlineType;
+    strikeout?: StrikeoutType;
+    fontRef: FontRef;
+    spacing?: number;
+    relSize?: number;
+    charOffset?: number;
+    useFontSpace?: boolean;
+    useKerning?: boolean;
+}
+interface FontRef {
+    hangul: number;
+    latin: number;
+    hanja: number;
+    japanese: number;
+    other: number;
+    symbol: number;
+    user: number;
+}
+type UnderlineType = 'NONE' | 'BOTTOM' | 'CENTER' | 'TOP';
+type StrikeoutType = 'NONE' | 'CONTINUOUS';
+interface ParaProperty {
+    id: number;
+    alignment?: Alignment;
+    heading?: HeadingType;
+    lineSpacing: SpacingValue;
+    paraMargin: ParaMargin;
+    tabDef?: TabDef;
+    breakBefore?: BreakType;
+}
+interface SpacingValue {
+    type: 'PERCENT' | 'FIXED' | 'BETWEEN_LINES' | 'AT_LEAST';
+    value: number;
+}
+interface ParaMargin {
+    left: number;
+    right: number;
+    indent: number;
+    prevSpacing: number;
+    nextSpacing: number;
+}
+interface TabDef {
+    autoTabLeft?: boolean;
+    autoTabRight?: boolean;
+    tabs?: TabItem[];
+}
+interface TabItem {
+    pos: number;
+    type: 'LEFT' | 'RIGHT' | 'CENTER' | 'DECIMAL';
+    leader: 'NONE' | 'SOLID' | 'DASH' | 'DOT';
+}
+type Alignment = 'JUSTIFY' | 'LEFT' | 'RIGHT' | 'CENTER' | 'DISTRIBUTE' | 'DISTRIBUTE_SPACE';
+type HeadingType = 'NONE' | 'OUTLINE' | 'NUMBER' | 'BULLET';
+type BreakType = 'NONE' | 'PAGE' | 'COLUMN' | 'SECTION';
+interface Style {
+    id: number;
+    type: 'PARA' | 'CHAR';
+    name: string;
+    engName?: string;
+    paraPrIDRef?: number;
+    charPrIDRef?: number;
+    nextStyleIDRef?: number;
+}
+interface BorderFill {
+    id: number;
+    borders: {
+        left: BorderLine;
+        right: BorderLine;
+        top: BorderLine;
+        bottom: BorderLine;
+    };
+    fillBrush?: FillBrush;
+    threeD?: boolean;
+    shadow?: boolean;
+    slash?: SlashType;
+    backSlash?: SlashType;
+}
+interface BorderLine {
+    type: BorderLineType;
+    width: BorderWidth;
+    color: number;
+}
+type BorderLineType = 'NONE' | 'SOLID' | 'DASH' | 'DOT' | 'DASH_DOT' | 'DASH_DOT_DOT' | 'LONG_DASH' | 'CIRCLE' | 'DOUBLE_SLIM' | 'SLIM_THICK' | 'THICK_SLIM' | 'SLIM_THICK_SLIM';
+type BorderWidth = '0.1mm' | '0.12mm' | '0.15mm' | '0.2mm' | '0.25mm' | '0.3mm' | '0.4mm' | '0.5mm' | '0.6mm' | '0.7mm' | '1.0mm' | '1.5mm' | '2.0mm' | '3.0mm' | '4.0mm' | '5.0mm';
+type SlashType = 'NONE' | 'CENTER' | 'COUNTER_CENTER';
+interface FillBrush {
+    type: 'SOLID' | 'GRADIENT' | 'IMAGE' | 'NONE';
+    faceColor?: number;
+    patternColor?: number;
+    patternType?: PatternType;
+}
+type PatternType = 'NONE' | 'HORIZONTAL' | 'VERTICAL' | 'BACKSLASH' | 'SLASH' | 'CROSS' | 'CROSS_DIAGONAL';
+interface BulletProperty {
+    id: number;
+    bulletChar: string;
+    bulletSize?: number;
+}
+interface NumberingProperty {
+    id: number;
+    levels: NumberingLevel[];
+}
+interface NumberingLevel {
+    format: NumberFormat;
+    prefix?: string;
+    suffix?: string;
+    start?: number;
+}
+type NumberFormat = 'DIGIT' | 'CIRCLE_DIGIT' | 'ROMAN_CAPITAL' | 'ROMAN_SMALL' | 'LATIN_CAPITAL' | 'LATIN_SMALL' | 'HANGUL' | 'CIRCLED_HANGUL' | 'HANJA';
+interface Section {
+    def: SectionDef;
+    paragraphs: Paragraph[];
+}
+interface SectionDef {
+    pageWidth: number;
+    pageHeight: number;
+    pageMargin: PageMargin;
+    landscape?: boolean;
+    gutterType?: 'LEFT_ONLY' | 'LEFT_RIGHT' | 'TOP_BOTTOM';
+    columns?: ColumnDef;
+    headerFooter?: HeaderFooterDef;
+}
+interface PageMargin {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    header: number;
+    footer: number;
+    gutter: number;
+}
+interface ColumnDef {
+    type: 'NORMAL' | 'DISTRIBUTE' | 'PARALLEL';
+    count: number;
+    gap: number;
+    sameSizes?: boolean;
+}
+interface HeaderFooterDef {
+    header?: SubDocument;
+    footer?: SubDocument;
+}
+interface SubDocument {
+    paragraphs: Paragraph[];
+}
+interface Paragraph {
+    paraPrIDRef: number;
+    styleIDRef: number;
+    runs: Run[];
+}
+type Run = TextRun | TableRun | PictureRun | DrawingRun | BreakRun;
+interface TextRun {
+    t: 'text';
+    text: string;
+    charPrIDRef: number;
+}
+interface TableRun {
+    t: 'table';
+    table: Table;
+    charPrIDRef: number;
+}
+interface PictureRun {
+    t: 'picture';
+    picture: Picture;
+    charPrIDRef: number;
+}
+interface DrawingRun {
+    t: 'drawing';
+    drawing: DrawingObject;
+    charPrIDRef: number;
+}
+interface BreakRun {
+    t: 'break';
+    breakType: 'LINE' | 'PAGE' | 'COLUMN' | 'SECTION';
+    charPrIDRef: number;
+}
+interface Table {
+    rows: TableRow[];
+    borderFillIDRef: number;
+    cellSpacing?: number;
+    cellPadding?: CellPadding;
+    width: number;
+    rowCount: number;
+    colCount: number;
+    colWidths: number[];
+}
+interface TableRow {
+    cells: TableCell[];
+    height: number;
+}
+interface TableCell {
+    paragraphs: Paragraph[];
+    colSpan: number;
+    rowSpan: number;
+    width: number;
+    height: number;
+    borderFillIDRef: number;
+    padding?: CellPadding;
+}
+interface CellPadding {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+interface Picture {
+    binDataIDRef: number;
+    width: number;
+    height: number;
+    offsetX?: number;
+    offsetY?: number;
+    cropRect?: CropRect;
+}
+interface CropRect {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+interface DrawingObject {
+    type: 'line' | 'rect' | 'ellipse' | 'polygon' | 'arc';
+    width: number;
+    height: number;
+    points?: {
+        x: number;
+        y: number;
+    }[];
+    lineColor?: number;
+    lineWidth?: number;
+    fillBrush?: FillBrush;
+}
+interface BinDataItem {
+    id: number;
+    format: 'jpg' | 'png' | 'gif' | 'bmp' | 'tiff' | 'wmf' | 'emf';
+    name: string;
+    data: Uint8Array;
+}
+interface WriteOptions {
+    compress?: boolean;
+}
+interface ReadOptions {
+    partial?: boolean;
+}
+
+interface TextStyleOptions {
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+    underline?: boolean;
+    strikeout?: boolean;
+    fontName?: string;
+}
+interface StyledSegment {
+    text: string;
+    style?: TextStyleOptions;
+}
+interface PageSettings {
+    width?: number;
+    height?: number;
+    landscape?: boolean;
+    marginLeft?: number;
+    marginRight?: number;
+    marginTop?: number;
+    marginBottom?: number;
+}
+interface TableOptions {
+    headerRow?: boolean;
+    borderStyle?: BorderLineType;
+    colWidths?: number[];
+    cellPadding?: number;
+    width?: number;
+}
+interface ImageOptions {
+    width: number;
+    height: number;
+}
+interface CellMerge {
+    row: number;
+    col: number;
+    rowSpan: number;
+    colSpan: number;
+}
+interface ColumnSettings {
+    count: number;
+    gap?: number;
+    type?: 'NORMAL' | 'DISTRIBUTE' | 'PARALLEL';
+}
+interface HeaderFooterOptions {
+    header?: string;
+    footer?: string;
+}
+declare class HWPXBuilder {
+    private doc;
+    private charPrIdCounter;
+    private paraPrIdCounter;
+    private borderFillIdCounter;
+    private binDataIdCounter;
+    private charPrCache;
+    constructor();
+    /** 단일 스타일 문단 추가 */
+    addParagraph(text: string, style?: TextStyleOptions): this;
+    /** 복수 스타일 세그먼트로 구성된 문단 추가 */
+    addStyledText(segments: StyledSegment[]): this;
+    /** 빈 문단(빈 줄) 추가 */
+    addEmptyParagraph(): this;
+    /** 페이지 설정 변경 */
+    setPageSettings(opts: PageSettings): this;
+    /** 테이블 추가 (string[][] 데이터, 셀 병합은 merges 옵션) */
+    addTable(data: string[][], opts?: TableOptions & {
+        merges?: CellMerge[];
+    }): this;
+    /** 이미지 추가 */
+    addImage(data: Uint8Array, format: BinDataItem['format'], opts: ImageOptions): this;
+    /** 머리글/바닥글 설정 */
+    setHeaderFooter(opts: HeaderFooterOptions): this;
+    /** 다단 설정 */
+    setColumns(opts: ColumnSettings): this;
+    /** 새 섹션 시작 */
+    addSection(): this;
+    /** 문서 빌드 */
+    build(): HWPXDocument;
+    private currentSection;
+    private getOrCreateCharPr;
+    private ensureFont;
+    private getOrCreateTableBorderFill;
+    private styleKey;
+}
+
+declare function createDefaultFontFaces(): FontFace[];
+declare function createDefaultCharProperty(id?: number): CharProperty;
+declare function createDefaultParaProperty(id?: number): ParaProperty;
+declare function createDefaultBorderFill(id?: number): BorderFill;
+declare function createDefaultStyles(): Style[];
+declare function createDefaultSectionDef(): SectionDef;
+declare function createDefaultHead(): DocumentHead;
+declare function createDefaultMeta(): DocumentMeta;
+declare function createDefaultDocument(): HWPXDocument;
+
+declare function mmToHwpunit(mm: number): number;
+declare function hwpunitToMm(hu: number): number;
+declare function ptToHwpunit(pt: number): number;
+declare function hwpunitToPt(hu: number): number;
+declare function pxToHwpunit(px: number, dpi?: number): number;
+declare function hwpunitToPx(hu: number, dpi?: number): number;
+/** 한글 글자 크기 단위: 1pt = 100 unit */
+declare function ptToCharHeight(pt: number): number;
+declare function charHeightToPt(height: number): number;
+
+declare function hexToColorref(hex: string): number;
+declare function colorrefToHex(colorref: number): string;
+/** COLORREF를 "R, G, B" 형식 문자열로 */
+declare function colorrefToRgbString(colorref: number): string;
+/** 0x00RRGGBB (일반 RGB 정수)를 COLORREF로 변환 */
+declare function rgbToColorref(rgb: number): number;
+
+declare class IdCounter {
+    private value;
+    constructor(start?: number);
+    next(): number;
+    current(): number;
+    reset(start?: number): void;
+}
+
+type DocumentFormat = 'hwpx' | 'hwp5' | 'unknown';
+/** 바이트 데이터의 magic bytes로 문서 포맷 감지 */
+declare function detectFormat(data: Uint8Array): DocumentFormat;
+
+type index_DocumentFormat = DocumentFormat;
+type index_IdCounter = IdCounter;
+declare const index_IdCounter: typeof IdCounter;
+declare const index_charHeightToPt: typeof charHeightToPt;
+declare const index_colorrefToHex: typeof colorrefToHex;
+declare const index_colorrefToRgbString: typeof colorrefToRgbString;
+declare const index_detectFormat: typeof detectFormat;
+declare const index_hexToColorref: typeof hexToColorref;
+declare const index_hwpunitToMm: typeof hwpunitToMm;
+declare const index_hwpunitToPt: typeof hwpunitToPt;
+declare const index_hwpunitToPx: typeof hwpunitToPx;
+declare const index_mmToHwpunit: typeof mmToHwpunit;
+declare const index_ptToCharHeight: typeof ptToCharHeight;
+declare const index_ptToHwpunit: typeof ptToHwpunit;
+declare const index_pxToHwpunit: typeof pxToHwpunit;
+declare const index_rgbToColorref: typeof rgbToColorref;
+declare namespace index {
+  export { type index_DocumentFormat as DocumentFormat, index_IdCounter as IdCounter, index_charHeightToPt as charHeightToPt, index_colorrefToHex as colorrefToHex, index_colorrefToRgbString as colorrefToRgbString, index_detectFormat as detectFormat, index_hexToColorref as hexToColorref, index_hwpunitToMm as hwpunitToMm, index_hwpunitToPt as hwpunitToPt, index_hwpunitToPx as hwpunitToPx, index_mmToHwpunit as mmToHwpunit, index_ptToCharHeight as ptToCharHeight, index_ptToHwpunit as ptToHwpunit, index_pxToHwpunit as pxToHwpunit, index_rgbToColorref as rgbToColorref };
+}
+
+declare class HWPXError extends Error {
+    constructor(message: string);
+}
+declare class HWPXValidationError extends HWPXError {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+
+/**
+ * HWPXDocument를 .hwpx 바이너리(Uint8Array)로 직렬화
+ */
+declare function write(doc: HWPXDocument, opts?: WriteOptions): Uint8Array;
+/**
+ * .hwpx 또는 .hwp 바이너리(Uint8Array)를 HWPXDocument로 파싱
+ * 포맷 자동 감지 (HWPX ZIP / HWP5 OLE)
+ */
+declare function read(data: Uint8Array, opts?: ReadOptions): HWPXDocument;
+
+export { type BinDataItem, type BorderFill, type BorderLine, type BreakRun, type BulletProperty, type CellMerge, type CellPadding, type CharProperty, type ColumnDef, type ColumnSettings, type DocumentHead, type DocumentMeta, type DrawingObject, type DrawingRun, type FillBrush, type FontFace, HWPXBuilder, type HWPXDocument, HWPXError, HWPXValidationError, type HeaderFooterDef, type HeaderFooterOptions, type ImageOptions, type NumberingLevel, type NumberingProperty, type PageMargin, type PageSettings, type ParaProperty, type Paragraph, type Picture, type PictureRun, type ReadOptions, type Run, type Section, type SectionDef, type Style, type StyledSegment, type SubDocument, type Table, type TableCell, type TableOptions, type TableRow, type TableRun, type TextRun, type TextStyleOptions, type WriteOptions, createDefaultBorderFill, createDefaultCharProperty, createDefaultDocument, createDefaultFontFaces, createDefaultHead, createDefaultMeta, createDefaultParaProperty, createDefaultSectionDef, createDefaultStyles, read, index as utils, write };