hwpx-ts/README.md

TypeScript library for reading and writing HWPX files

# hwpx-ts

TypeScript/JavaScript library for reading and writing HWPX (한글) files.

## Installation

```bash
npm install hwpx-ts
# or
yarn add hwpx-ts
# or
pnpm add hwpx-ts
```

## Usage

### Reading HWPX Files

```typescript
import { HwpxReader, readHwpxFile } from 'hwpx-ts';

// Node.js - from file
const reader = await readHwpxFile('./document.hwpx');

// Browser - from ArrayBuffer
const response = await fetch('/document.hwpx');
const data = await response.arrayBuffer();
const reader = new HwpxReader(data);
await reader.parse();

// Get text content
const text = reader.getText();
console.log(text);

// Get document info
const info = reader.getInfo();
console.log(info.paragraphCount, info.tableCount, info.imageCount);

// Get paragraphs
const paragraphs = reader.getParagraphs();

// Search
const results = reader.search('검색어');

// Convert to Markdown
const markdown = reader.toMarkdown();

// Convert to JSON
const json = reader.toJson();
```

### Creating HWPX Files

```typescript
import { HwpxExporter } from 'hwpx-ts';

const exporter = new HwpxExporter();

// Add heading
exporter.addHeading('문서 제목', 1);

// Add paragraph
exporter.addParagraph('본문 텍스트입니다.', {
  bold: true,
  alignment: 'center',
});

// Add table
exporter.addTable([
  ['이름', '나이', '직업'],
  ['홍길동', '30', '개발자'],
  ['김철수', '25', '디자이너'],
]);

// Add page break
exporter.addPageBreak();

// From Markdown
exporter.fromMarkdown(`
# 제목

본문 내용

## 소제목

- 목록 1
- 목록 2
`);

// Build and save (Node.js)
await exporter.saveToFile('./output.hwpx');

// Build as Uint8Array (Browser)
const data = await exporter.build();
const blob = new Blob([data], { type: 'application/octet-stream' });
```

### Unit Conversions

```typescript
import { mmToHwpunit, hwpunitToMm, ptToHwpunit, hwpunitToPt } from 'hwpx-ts';

// Convert 10mm to HWPUNIT
const hwpunit = mmToHwpunit(10);  // 567

// Convert HWPUNIT to mm
const mm = hwpunitToMm(567);  // 10

// Convert 12pt to HWPUNIT
const hwpunit2 = ptToHwpunit(12);  // 240
```

## API Reference

### HwpxReader

| Method | Description |
|--------|-------------|
| `parse()` | Parse the HWPX file |
| `getText()` | Get full text content |
| `getParagraphs()` | Get all paragraphs |
| `getParagraph(index)` | Get paragraph by index |
| `getParagraphText(index)` | Get paragraph text by index |
| `getTables()` | Get all tables |
| `getImages()` | Get all images |
| `getImageData(id)` | Get image binary data |
| `getInfo()` | Get document info |
| `search(query, caseSensitive?)` | Search text |
| `toJson()` | Convert to JSON |
| `toMarkdown()` | Convert to Markdown |

### HwpxExporter

| Method | Description |
|--------|-------------|
| `addParagraph(text, options?)` | Add a paragraph |
| `addHeading(text, level?, alignment?)` | Add a heading |
| `addTable(data, options?)` | Add a table |
| `addImage(data, filename?, options?)` | Add an image |
| `addPageBreak()` | Add a page break |
| `addLineBreak()` | Add an empty line |
| `fromMarkdown(markdown)` | Create from Markdown |
| `build()` | Build as Uint8Array |
| `saveToFile(path)` | Save to file (Node.js) |

## Types

```typescript
interface DocumentInfo {
  paragraphCount: number;
  tableCount: number;
  imageCount: number;
  sectionCount: number;
  binaryItems: number;
}

interface Paragraph {
  inlines: InlineElement[];
  alignment?: AlignmentType;
  // ...
}

interface Table {
  rowCount: number;
  colCount: number;
  cells: TableCell[];
  // ...
}

type AlignmentType = 'left' | 'right' | 'center' | 'justify' | 'distribute';
```

## License

AGPL-3.0