HWPX to Typst 변환기

한글(HWPX) 양식 파일을 Typst 템플릿으로 변환하고 웹에서 즉시 편집할 수 있는 도구입니다.

주요 기능

• HWPX → Typst 자동 변환: Rust 기반의 고성능 파서가 HWPX 파일을 Typst 소스 코드로 변환합니다.
• 폼 필드 자동 감지: 문서 내의 입력 안내 텍스트, 괄호 설명, 빈 셀, 체크박스 등을 감지하여 입력 UI를 생성합니다.
• 클라이언트 사이드 변환: WebAssembly(WASM)를 사용하여 서버 없이 브라우저에서 모든 변환 과정을 처리합니다.
• 실시간 PDF 미리보기: 입력한 내용을 바탕으로 Typst 엔진이 PDF를 생성하여 즉시 확인할 수 있습니다.

사전 요구 사항

이 프로젝트를 빌드하고 실행하려면 다음 도구들이 필요합니다.

• Rust: rustup을 통해 설치 (cargo 1.94.0 이상 권장)
• Node.js: 18 버전 이상
• wasm-pack: cargo install wasm-pack으로 설치
• wasm32 타겟: rustup target add wasm32-unknown-unknown

빠른 시작

1. WASM 빌드

Rust 코드를 웹에서 사용할 수 있도록 WebAssembly로 빌드합니다.

wasm-pack build crates/wasm-bindings --target web --out-dir ../../web/src/wasm

2. 웹 앱 실행

Vite 개발 서버를 실행하여 브라우저에서 확인합니다.

cd web
npm install
npm run dev

브라우저에서 http://localhost:5173에 접속하여 서비스를 이용할 수 있습니다.

사용법

1. 파일 업로드: 브라우저에서 .hwpx 파일을 드래그하거나 클릭하여 선택합니다.
2. 자동 변환: 업로드 즉시 HWPX 파일이 Typst 템플릿으로 변환되며, 폼 필드가 자동으로 감지됩니다.
3. 양식 입력: 왼쪽 패널에 나타나는 입력 필드에 내용을 작성합니다. 섹션별로 구분된 아코디언 메뉴를 통해 편리하게 입력할 수 있습니다.
4. PDF 생성 및 다운로드: "PDF 생성" 버튼을 클릭하여 결과물을 미리 보고 다운로드합니다.

개발자 가이드

프로젝트 구조

• crates/hwpx-parser: HWPX ZIP 파일을 XML로 파싱하여 중간 표현(IR)으로 변환합니다.
• crates/typst-codegen: IR을 바탕으로 Typst 소스 코드를 생성합니다.
• crates/form-detector: 문서 내의 특정 패턴을 분석하여 폼 필드를 자동으로 감지합니다.
• crates/wasm-bindings: Rust 기능을 웹에서 사용할 수 있도록 wasm-bindgen 바인딩을 제공합니다.
• web/: Vite와 React 기반의 웹 애플리케이션입니다.

폼 필드 감지 알고리즘

form-detector는 다음 5가지 패턴을 분석하여 입력 필드를 생성합니다.

1. 파란색 텍스트: #0000FF 색상의 텍스트를 사용자 입력 안내로 인식합니다.
2. 괄호 설명: (기관번호), (부서명) 등 괄호 안의 텍스트를 필드 레이블로 사용합니다.
3. 빈 셀: 테이블 내의 빈 셀을 입력 영역으로 인식하며, 높이에 따라 텍스트 또는 텍스트 영역으로 구분합니다.
4. 체크박스: □ (U+25A1) 기호를 체크박스 필드로 변환합니다.
5. TRL 선택: ○ (U+25CB) 기호와 "TRL" 텍스트가 함께 있는 경우 TRL 선택 필드로 인식합니다.

테스트 실행

Rust 로직의 정합성을 확인하기 위해 다음 명령어를 사용합니다.

cargo test

지원 범위

지원 항목

• HWPX: 한글 2014 이상에서 생성된 HWPX 파일
• 테이블: 병합된 셀(colspan/rowspan)을 포함한 복잡한 표 구조
• 텍스트 스타일: 폰트, 크기, 색상, 밑줄 등 기본 서식
• 페이지 레이아웃: A4 용지 기준 가로/세로 방향 및 여백 설정
• 폼 요소: 체크박스, 번호 매기기 등

미지원 항목 (MVP 범위 외)

• HWP: 구형 바이너리 포맷 (HWPX만 지원)
• 이미지 및 OLE 객체: 문서 내 삽입된 그림이나 개체
• 매크로: 한글 내부 스크립트 및 매크로 기능
• 암호 보호: 비밀번호가 설정된 문서

라이선스

이 프로젝트는 MIT 라이선스를 따릅니다.

hwpx_to_typst