# Allorion Exporting HTML to DOCX

![npm](https://img.shields.io/npm/v/allorion-exporting-html-to-docx?style=flat-square)
![license](https://img.shields.io/npm/l/allorion-exporting-html-to-docx?style=flat-square)

## Описание

`allorion-exporting-html-to-docx` — это мощный npm-модуль для браузера, который конвертирует HTML в DOCX, сохраняя структуру, стили и форматирование. Поддерживает параграфы, списки, таблицы, фигуры и вложенные стили текста.

## Инициализация

Для использования модуля требуется лицензия. Получить ключ и подпись можно через Telegram [@a11ori](https://t.me/a11ori) или email `buy@allorion.ru`.

```javascript
const license = {
    licenseKey: 'licenseKey',
    signature: 'signature',
};

export const exportHtmlToDocx = await initializeModule(license);
```

## Использование

```javascript
exportHtmlToDocx({
    fileName: 'nameFile',
    divId: 'id-div-blok',
    format: 'A4',
    orientation: 'vertical'
}).then(flag => console.log(flag));

// Или
const flag = await exportHtmlToDocx({
    fileName: 'nameFile',
    divId: 'id-div-blok',
    format: 'A4',
    orientation: 'vertical'
});
```

## API

### `exportHtmlToDocx({ fileName, jsxElement, format, orientation, divId }: IExportingHtmlToDocx) => Promise<boolean>`

| Параметр | Тип | Описание |
|-----------|-----|----------|
| `fileName` | `string` | Имя создаваемого файла |
| `divId` | `string` | ID HTML-элемента для экспорта |
| `jsxElement` | `JSX.Element` | Передача JSX напрямую (альтернатива divId) |
| `format` | `string` | Размер страницы (поддерживается: A1, A2, A3, A4) |
| `orientation` | `string` | Ориентация страницы (`vertical` или `landscape`) |

## Поддерживаемые HTML-теги
- Заголовки: `<h1>` … `<h6>`
- Параграфы и текст: `<p>`, `<span>`
- Разрывы строк: `<br>`
- Списки: `<ul>`, `<ol>`, `<li>`
- Таблицы: `<table>`, `<tr>`, `<td>`, `<th>`
- Фигуры: `<figure>`

## Поддерживаемые dataset атрибуты

| Атрибут | Описание | Применение | Пример |
|---------|----------|------------|--------|
| `data-text-bold` | Жирный текст | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-bold>Жирный</span>` |
| `data-text-italic` | Курсив | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-italic>Курсив</span>` |
| `data-text-underlined` | Подчёркнутый | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-underlined>Подчёркнутый</span>` |
| `data-text-color` | Цвет текста в HEX (без `#`) | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-color="FF0000">Красный</span>` |
| `data-text-highlight` | Цвет подсветки (`highlight-*`) | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-highlight="yellow">Выделение</span>` |
| `data-font-size` | Размер шрифта в пунктах | `<p>`, `<span>`, `<li>`, `<td>`, `<th>` | `<p data-font-size="24">Текст 24pt</p>` |
| `data-text-align` | Выравнивание текста (`left`, `center`, `right`, `justify`) | `<p>`, `<li>`, `<td>`, `<th>` | `<p data-text-align="center">Центр</p>` |
| `data-no-export` | Пропустить экспорт | Любой элемент | `<span data-no-export>Не экспортировать</span>` |

### Поддерживаемые цвета подсветки

| Цвет | HEX/Описание |
|------|--------------|
| yellow | Жёлтый |
| green | Зелёный |
| cyan | Голубой |
| magenta | Пурпурный |
| blue | Синий |
| red | Красный |
| darkBlue | Тёмно-синий |
| darkCyan | Тёмно-голубой |
| darkGreen | Тёмно-зелёный |
| darkMagenta | Тёмно-пурпурный |
| darkRed | Тёмно-красный |
| darkYellow | Тёмно-жёлтый |
| darkGray | Тёмно-серый |
| lightGray | Светло-серый |
| black | Чёрный |

Применение: `<span data-text-highlight="yellow">Текст с подсветкой</span>`.

### Пример комплексного блока

```html
<p data-text-bold data-text-color="0070C0" data-font-size="24" data-text-align="center">
  Это <span data-text-italic data-text-color="FF0000">тестовый параграф</span> с разными стилями.
</p>

<ul data-text-align="justify" data-text-color="006600" data-font-size="20">
  <li>Первый элемент списка</li>
  <li data-text-bold data-text-color="FF6600">
    Второй элемент <span data-text-italic>со вложенным стилем</span>
  </li>
</ul>

<table>
  <tr>
    <td data-text-bold data-font-size="18">Ячейка 1</td>
    <td data-text-italic data-text-highlight="yellow">Ячейка 2</td>
  </tr>
</table>
```

## Лицензия
См. файл [LICENSE](./LICENSE).

---

# Allorion Exporting HTML to DOCX (English)

![npm](https://img.shields.io/npm/v/allorion-exporting-html-to-docx?style=flat-square)
![license](https://img.shields.io/npm/l/allorion-exporting-html-to-docx?style=flat-square)

## Description

`allorion-exporting-html-to-docx` is a powerful npm module for browsers that converts HTML to DOCX while preserving structure, styles, and formatting. Supports paragraphs, lists, tables, figures, and nested text styles.

## Initialization

A license is required. Obtain a license key and signature via Telegram [@a11ori](https://t.me/a11ori) or email `buy@allorion.ru`.

```javascript
const license = {
    licenseKey: 'licenseKey',
    signature: 'signature',
};

export const exportHtmlToDocx = await initializeModule(license);
```

## Usage

```javascript
exportHtmlToDocx({
    fileName: 'nameFile',
    divId: 'id-div-block',
    format: 'A4',
    orientation: 'vertical'
}).then(flag => console.log(flag));

// Or
const flag = await exportHtmlToDocx({
    fileName: 'nameFile',
    divId: 'id-div-block',
    format: 'A4',
    orientation: 'vertical'
});
```

## API

### `exportHtmlToDocx({ fileName, jsxElement, format, orientation, divId }: IExportingHtmlToDocx) => Promise<boolean>`

| Parameter | Type | Description |
|-----------|-----|-------------|
| `fileName` | `string` | Name of the exported file |
| `divId` | `string` | ID of the HTML element to export |
| `jsxElement` | `JSX.Element` | Direct JSX input (alternative to divId) |
| `format` | `string` | Page size (supports: A1, A2, A3, A4) |
| `orientation` | `string` | Page orientation (`vertical` or `landscape`) |

## Supported HTML Tags
- Headings: `<h1>` … `<h6>`
- Paragraphs and text: `<p>`, `<span>`
- Line breaks: `<br>`
- Lists: `<ul>`, `<ol>`, `<li>`
- Tables: `<table>`, `<tr>`, `<td>`, `<th>`
- Figures: `<figure>`

## Supported dataset attributes

| Attribute | Description | Usage | Example |
|-----------|------------|-------|--------|
| `data-text-bold` | Bold text | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-bold>Bold</span>` |
| `data-text-italic` | Italic | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-italic>Italic</span>` |
| `data-text-underlined` | Underlined | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-underlined>Underlined</span>` |
| `data-text-color` | Text color in HEX (without `#`) | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-color="FF0000">Red</span>` |
| `data-text-highlight` | Highlight color (`highlight-*`) | `<p>`, `<span>`, `<td>`, `<th>` | `<span data-text-highlight="yellow">Highlight</span>` |
| `data-font-size` | Font size in points | `<p>`, `<span>`, `<li>`, `<td>`, `<th>` | `<p data-font-size="24">Text 24pt</p>` |
| `data-text-align` | Text alignment (`left`, `center`, `right`, `justify`) | `<p>`, `<li>`, `<td>`, `<th>` | `<p data-text-align="center">Center</p>` |
| `data-no-export` | Skip exporting | Any element | `<span data-no-export>Skip export</span>` |

### Supported highlight colors

| Color | Description |
|-------|-------------|
| yellow | Yellow |
| green | Green |
| cyan | Cyan |
| magenta | Magenta |
| blue | Blue |
| red | Red |
| darkBlue | Dark Blue |
| darkCyan | Dark Cyan |
| darkGreen | Dark Green |
| darkMagenta | Dark Magenta |
| darkRed | Dark Red |
| darkYellow | Dark Yellow |
| darkGray | Dark Gray |
| lightGray | Light Gray |
| black | Black |

### Example complex block

```html
<p data-text-bold data-text-color="0070C0" data-font-size="24" data-text-align="center">
  This is <span data-text-italic data-text-color="FF0000">a test paragraph</span> with multiple styles.
</p>

<ul data-text-align="justify" data-text-color="006600" data-font-size="20">
  <li>First list item</li>
  <li data-text-bold data-text-color="FF6600">
    Second item <span data-text-italic>with nested style</span>
  </li>
</ul>

<table>
  <tr>
    <td data-text-bold data-font-size="18">Cell 1</td>
    <td data-text-italic data-text-highlight="yellow">Cell 2</td>
  </tr>
</table>
```

## License
Refer to the [LICENSE](./LICENSE) file.