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

package/LICENSE

@@ -0,0 +1,8 @@
+AZ Editor — proprietary software
+
+AZ Editor's own code is UNLICENSED. No open-source license is granted for it.
+Public availability on npm does not grant an open-source license.
+Any additional rights require permission from the rights holder.
+
+Third-party software and fonts retain their respective licenses. See
+THIRD_PARTY_NOTICES.md and dist/licenses for their license texts and notices.

package/README.md

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+# AZ Editor — React-библиотека для DOCX
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Встраиваемый редактор документов 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).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,30 @@
+# Third-party software
+
+AZ Editor 0.1 is an integration prototype. Its OOXML parser, serializer, layout engine
+and editing surface come from [EigenPal docx-editor](https://github.com/eigenpal/docx-editor).
+The upstream packages are consumed without source modifications. AZ Editor adds its
+own React adapter, file validation, document lifecycle, demo interface and translations.
+
+| Package | Version | Declared license |
+| --- | --- | --- |
+| @docx-editor.dev/core | 2.27.0 | Apache-2.0 |
+| @docx-editor.dev/react | 2.27.0 | Apache-2.0 |
+| @docx-editor.dev/i18n | 2.27.0 | Apache-2.0 |
+| @docx-editor.dev/fonts | 2.27.0 | Apache-2.0 AND OFL-1.1 AND LicenseRef-GUST-Font-License |
+| React / React DOM | 19.3.0 | MIT |
+| JSZip | 3.10.2 | MIT OR GPL-3.0-or-later (used under MIT) |
+
+The font package includes Carlito, Caladea, Liberation and TeX Gyre assets. Its
+original notices include OFL, GUST and LPPL text. Font substitution is not a promise
+of matching Microsoft Word layout. Microsoft font files are not supplied here.
+
+Both build commands preserve the installed runtime packages' LICENSE, COPYING,
+NOTICE, THIRD_PARTY_NOTICES and licenses directories in the output's `licenses/`.
+That directory also contains a versioned inventory of runtime dependencies.
+Keep those files with redistributed builds; upstream notices include notices for
+code and prebuilt assets bundled inside upstream packages.
+
+No commercial Pro modules are installed in this prototype. Development tools and
+the synthetic DOCX fixture generator are separate dependencies in package-lock.json.
+AZ Editor's own code is proprietary (UNLICENSED); see LICENSE. This restriction
+does not replace or limit the licenses granted for the third-party code above.

package/dist/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,30 @@
+# Third-party software
+
+AZ Editor 0.1 is an integration prototype. Its OOXML parser, serializer, layout engine
+and editing surface come from [EigenPal docx-editor](https://github.com/eigenpal/docx-editor).
+The upstream packages are consumed without source modifications. AZ Editor adds its
+own React adapter, file validation, document lifecycle, demo interface and translations.
+
+| Package | Version | Declared license |
+| --- | --- | --- |
+| @docx-editor.dev/core | 2.27.0 | Apache-2.0 |
+| @docx-editor.dev/react | 2.27.0 | Apache-2.0 |
+| @docx-editor.dev/i18n | 2.27.0 | Apache-2.0 |
+| @docx-editor.dev/fonts | 2.27.0 | Apache-2.0 AND OFL-1.1 AND LicenseRef-GUST-Font-License |
+| React / React DOM | 19.3.0 | MIT |
+| JSZip | 3.10.2 | MIT OR GPL-3.0-or-later (used under MIT) |
+
+The font package includes Carlito, Caladea, Liberation and TeX Gyre assets. Its
+original notices include OFL, GUST and LPPL text. Font substitution is not a promise
+of matching Microsoft Word layout. Microsoft font files are not supplied here.
+
+Both build commands preserve the installed runtime packages' LICENSE, COPYING,
+NOTICE, THIRD_PARTY_NOTICES and licenses directories in the output's `licenses/`.
+That directory also contains a versioned inventory of runtime dependencies.
+Keep those files with redistributed builds; upstream notices include notices for
+code and prebuilt assets bundled inside upstream packages.
+
+No commercial Pro modules are installed in this prototype. Development tools and
+the synthetic DOCX fixture generator are separate dependencies in package-lock.json.
+AZ Editor's own code is proprietary (UNLICENSED); see LICENSE. This restriction
+does not replace or limit the licenses granted for the third-party code above.