@makhmudov.kay/az-editor 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -1,217 +1,70 @@
-# AZ Editor — React-библиотека для DOCX
-
-Встраиваемый редактор документов Word: текст, таблицы, страницы, импорт и сохранение
-DOCX. Пакет `@makhmudov.kay/az-editor` использует открытое ядро `@docx-editor.dev` 2.27.0.
-Демонстрационное приложение отделено от библиотеки: его шапка, боковые панели,
-уведомления, обработка файлов и серверные настройки не входят в компонент.
-
-Совпадение с Microsoft Word один в один пока не подтверждено. Подробности:
-[проверка совместимости](docs/compatibility-2026-10-08.md).
-
-Для текущего Hujjat (ограниченный HTML → JSON по локалям → mPDF) добавлен адаптер:
-`exportHujjat()`, `importHujjatTemplate()` и `requestHujjatPreview()`.
-[Инструкция интеграции и ограничения](docs/hujjat-integration.ru.md).
-
-Для будущего подключения рядом с существующим редактором доступен `AzHtmlEditor`:
-`initialHtml` → отдельный черновик → `await ref.exportHtml()`.
-В комплекте есть пример применения/отмены и [инструкция для agrodox-front](docs/agrodox-integration.ru.md).
-Сам проект agrodox-front не изменён; подключение выполняет приложение отдельно.
-
-## Запуск демо
-
-Node.js 24.15+ (ветка 24) или 26+, npm.
-
-```sh
-npm ci
-npm run dev
-```
-
-Откройте http://127.0.0.1:5173. Сразу откроется пустой документ. В меню «Файл» доступны
-создание документа, открытие DOCX, пример договора, скачивание DOCX/PDF и печать.
-Также можно перетащить DOCX в редактор. Сохранение не меняет исходный файл.
-
-Сборка автономна: код подготовки печатных страниц и профиль рендеринга находятся
-в `src/library/print-pages`. Соседний репозиторий backend не требуется.
-
-## Сборка и установка пакета
-
-```sh
-npm pack
-# В другом React-проекте:
-npm install /path/to/makhmudov.kay-az-editor-0.1.0-beta.1.tgz
-```
-
-`npm pack` автоматически запускает сборку. Архив содержит ES-модуль, CSS,
-TypeScript-декларации и сведения о лицензиях. React и React DOM 19 — peer dependencies.
-Пакет подготовлен к публичной публикации `@makhmudov.kay/az-editor@0.1.0-beta.1`.
-В `publishConfig` установлены `access: public` и `tag: beta`.
-Публичная публикация в npm бесплатна; для прямой публикации от имени аккаунта
-требуется двухфакторная аутентификация. Собственный код — `UNLICENSED`:
-публичный доступ не предоставляет открытую лицензию. Лицензии зависимостей сохраняются.
-Статус публикации проверяется в реестре; наличие архива ещё не означает,
-что версия опубликована.
-
-После публикации пакет можно установить без входа в npm:
-
-```sh
-npm install @makhmudov.kay/az-editor@beta
-```
-
-Нужен браузерный сборщик с поддержкой CSS, шрифтов и WASM; проверен Vite.
-В приложениях с серверным рендерингом подключайте редактор на клиенте.
-
-## Минимальное подключение
-
-```tsx
-import { useRef } from 'react';
-import {
-  AzDocumentEditor,
-  downloadDocx,
-  type AzDocumentEditorHandle,
-} from '@makhmudov.kay/az-editor';
-import '@makhmudov.kay/az-editor/styles.css';
-
-export function Editor() {
-  const editor = useRef<AzDocumentEditorHandle>(null);
-
-  async function save() {
-    if (!editor.current) return;
-    const bytes = await editor.current.save();
-    downloadDocx(bytes, 'document.docx');
-    // Вместо скачивания приложение может отправить bytes в свой API.
-  }
-
-  return (
-    <AzDocumentEditor
-      ref={editor}
-      document="blank"
-      title="Договор.docx"
-      style={{ height: 700 }}
-      onSave={save}
-      onChange={() => console.log('Документ изменён')}
-    />
-  );
-}
-```
-
-Без `document` создаётся пустой документ. Для импорта используйте
-`const opened = await readDocxFile(file)` и передавайте `opened.original` в `document`.
-При замене документа меняйте React `key`, чтобы сбросить историю предыдущего файла.
-Проверку несохранённых изменений выполняет приложение до замены `key`.
-
-Компонент занимает высоту контейнера. Задайте её через `style`/`className` или родителю.
-Минимальная высота, размеры окна и глобальные стили страницы не навязываются.
-
-## Настройка интерфейса
-
-```tsx
-<AzDocumentEditor
-  document={bytes}
-  style={{ height: '100%' }}
-  ui={{ menu: false, rulers: false, navigation: false, print: false }}
-/>
-
-// Поверхность документа без заголовка, меню, панели форматирования и линеек:
-<AzDocumentEditor document={bytes} ui={false} style={{ height: 600 }} />
-
-// Просмотр без редактирования:
-<AzDocumentEditor document={bytes} mode="view" style={{ height: 600 }} />
-```
-
-Все параметры `ui` по умолчанию включены:
-
-| Параметр | Назначение |
-| --- | --- |
-| `chrome` | Заголовок, меню и панель форматирования одним блоком |
-| `menu` | Меню «Файл», «Формат», «Вставка», «Рецензирование» |
-| `rulers` | Горизонтальная и вертикальная линейки |
-| `navigation` | Навигация по заголовкам и поиск |
-| `contextMenu` | Контекстное меню редактора |
-| `print` | Пункт печати и перехват Ctrl/Cmd+P нашим адаптером |
-
-`ui={false}` отключает эти элементы; редактирование остаётся доступным, если `mode="edit"`.
-Настройки интерфейса можно менять без повторного открытия документа и потери правок.
-`ui.chrome=false` использует поверхность движка без его рамки, включая встроенные линейки
-и навигацию. Для отдельных переключателей оставьте `chrome` включённым.
-
-Дополнительные параметры:
-
-| Prop | Назначение |
-| --- | --- |
-| `className`, `style` | Контейнер и размеры компонента |
-| `colorMode` | `light`, `dark`, `system`; меняется интерфейс, а не лист документа |
-| `i18n` | Каталог переводов; по умолчанию частичный русский с английскими запасными строками |
-| `locale` | Региональные правила дат и подписей, по умолчанию `ru-RU`; не переключает язык UI |
-| `labels` | Подписи `open`, `save`, `exportPdf`, `print` для действий адаптера |
-| `fonts` | Своя конфигурация шрифтов; при её замене перемонтируйте компонент |
-| `zoom`, `zoomMode` | Масштаб и режим подгонки страниц |
-| `renderTitleBarLeft`, `renderTitleBarRight` | Элементы приложения по краям заголовка |
-| `fileActions` | Дополнительные действия меню «Файл»: `{ id, label, onSelect, disabled? }` |
-| `actionsDisabled` | Блокировка файловых действий при загрузке/сохранении приложением |
-
-Для оформления используйте CSS, ограниченный вашим классом, например
-`.my-editor .docx-editor { --doc-primary: #2563eb; }`.
-Диалог локальной печати пока использует русские подписи.
-
-## Открытие, сохранение и PDF принадлежат приложению
-
-- `onOpen` — приложение выбирает источник и передаёт новые байты в компонент.
-- `onSave` — приложение получает байты через `ref.save()` и решает, куда их сохранить.
-- `onExportPdf` — приложение вызывает собственный сервис и скачивает результат.
-- `onChange` — правка содержимого; загрузка исходника не считается правкой.
-- `onStatusChange` — `{ pages, loading, error }`, без обязательной полосы статуса в библиотеке.
-- `onFontError` — сообщение о неудачной загрузке шрифта.
-
-Если обработчик `onOpen`, `onSave` или `onExportPdf` не передан, соответствующий пункт
-меню отсутствует. Компонент сам не обращается к серверу сохранения или генерации PDF.
-Ошибки асинхронных обработчиков приложение обрабатывает самостоятельно.
-
-Ref предоставляет `save(): Promise<ArrayBuffer>`, `focus()` и `print(): Promise<void>`.
-`print()` открывает локальный предпросмотр всех страниц, после которого используется
-диалог печати браузера. Ctrl/Cmd+S/O/P адаптер обрабатывает только внутри активного
-редактора; поля и кнопки вне компонента остаются под управлением приложения.
-
-Опциональные функции `requestPdf`, `downloadPdf` и `pdfRenderProfile` поддерживают
-контракт отдельного PDF-сервиса. У `requestPdf` можно задать `url`, `headers`, `signal`
-и собственный `fetcher`. Эти функции не вызываются при простом подключении редактора.
-Демо использует `/api/documents/export/pdf`; настройки прокси находятся в
-`.env.pdf.example`. Для другого бэкенда реализуйте свой `onExportPdf`.
-
-[ТЗ PDF-сервиса](docs/pdf-export-backend-spec.md) ·
-[Контракт OpenAPI](docs/pdf-export.openapi.yaml).
-
-## Проверки
-
-```sh
-npm test
-npm run build
-npm run build:demo
-npx playwright install chromium
-npm run test:e2e
-```
-
-Проверяются импорт и повторное открытие DOCX, правки текста и таблиц, undo/redo,
-сохранность исходных байтов, отказ от повреждённых файлов, защита несохранённых правок,
-экспорт текущего состояния в PDF, подготовка всех 12 страниц при виртуализации,
-встраивание в контейнер, скрытие UI, режим просмотра и сочетания клавиш приложения.
-
-`tests/browser/fixtures/embed.html` — пример отдельного приложения-потребителя без
-стилей демо. Личный корпус документов подключается отдельно через `AZ_EDITOR_CORPUS`;
-в обычном запуске его проверки пропускаются. Пользовательские файлы не входят в npm-пакет.
-
-## Ограничения
-
-Поддерживается DOCX до 30 МиБ; DOC, DOCM, PDF и защищённые паролем документы не являются
-входным форматом редактора. Шрифты-заменители и отличия вёрстки могут менять переносы.
-Сложные поля, формулы, плавающие объекты, исправления и комментарии требуют отдельной
-проверки. Адаптер Hujjat преобразует поддерживаемое содержимое в HTML/JSON и вызывает
-существующий PDF API. Авторизацию, сохранение и версии шаблонов подключает приложение;
-сквозная проверка с живым Hujjat пока не выполнена.
-
-Демо хранит правки в памяти до скачивания. Библиотека позволяет приложению реализовать
-свой процесс сохранения. Экспорт через Chromium воспроизводит вёрстку редактора,
-а Hujjat заново рассчитывает её через mPDF. Ни один из этих вариантов не является
-независимым эталоном Microsoft Word. Сборщик может предупреждать о размере ядра и Node-модулях
-в браузерном экспортере; сохранение из байтов проверяется в браузерных тестах.
-
-Лицензии и происхождение компонентов: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+# Az Editor
+
+React-библиотека для редактирования DOCX и HTML-документов с постраничным интерфейсом.
+Приложение управляет файлами, сохранением, авторизацией и подключением PDF-сервиса.
+
+**[Полное руководство по интеграции →](docs/integration.ru.md)**
+
+Установка, React + Vite, Next.js, DOCX, HTML-черновики, применение и отмена правок,
+переменные, JSON, PDF, шрифты, интерфейс, справочник API и устранение ошибок.
+
+## Установка
+
+```sh
+npm install @makhmudov.kay/az-editor@beta
+```
+
+Для воспроизводимой установки опубликованной версии:
+
+```sh
+npm install --save-exact @makhmudov.kay/az-editor@0.1.0-beta.3
+```
+
+Требуются React и React DOM 19, Node.js `^24.15.0 || >=26.0.0` для установки/сборки,
+браузерный сборщик с поддержкой CSS, шрифтов и WASM. Пакет — ESM с TypeScript-декларациями.
+Редактор работает в браузере; SSR компонента отключают.
+
+## Минимальное подключение
+
+```tsx
+import { AzDocumentEditor } from '@makhmudov.kay/az-editor';
+import '@makhmudov.kay/az-editor/styles.css';
+
+export function Editor() {
+  return <AzDocumentEditor document="blank" title="document.docx" style={{ height: 700 }} />;
+}
+```
+
+Для HTML используйте `AzHtmlEditor` с `initialHtml` и асинхронным `exportHtml()`.
+Открытие, сохранение и обработка ошибок подробно разобраны в [руководстве](docs/integration.ru.md).
+
+## Примеры для копирования
+
+- [DOCX: открытие, сохранение, несохранённые правки](examples/integration/DocxEditorExample.tsx)
+- [HTML: форма и отдельный черновик](examples/integration/HtmlFormExample.tsx)
+- [HTML: применение, отмена и диагностика](examples/integration/HtmlDraft.tsx)
+- [Свой API и PDF-сервис](examples/integration/server-api.ts)
+- [Загрузка собственных шрифтов](examples/integration/loadFonts.ts)
+
+Это исходники для копирования в приложение, а не дополнительные экспорты npm-пакета.
+
+## Разработка и сборка
+
+```sh
+npm ci
+npm run dev
+npm run build
+npm pack
+```
+
+Демо: `http://127.0.0.1:5173`. Сборка автономна. `npm pack` включает руководство,
+примеры, JS, CSS, типы и лицензии зависимостей.
+
+## Ограничения и лицензия
+
+Внешний вид и переносы могут отличаться от Microsoft Word или серверного PDF.
+HTML поддерживает ограниченный набор тегов и стилей; потери возвращаются в диагностике.
+Подробности и лимиты — в [руководстве](docs/integration.ru.md).
+
+Собственный код: [UNLICENSED](LICENSE). Публичная доступность не предоставляет открытую
+лицензию. Лицензии зависимостей: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).