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

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Изменения
+
+## 0.1.0-beta.11
+
+- Ctrl+Z отменяет, Ctrl+Y и Ctrl+Shift+Z повторяют действие в активном редакторе. Поддерживаются русская раскладка, Cmd на macOS, фокус на панели форматирования и развёрнутый режим.
+- Сочетания используют историю движка один раз за нажатие. Поля ввода, вложенные диалоги и соседние редакторы сохраняют собственную обработку; режим чтения и `actionsDisabled` блокируют изменение истории документа.
+
+## 0.1.0-beta.10
+
+- Разворачивание редактора на всю страницу и возврат по кнопке/Escape без пересоздания документа и истории отмены. Поддерживаются `fullscreen`, `onFullscreenChange` и `ui.fullscreen`.
+- Горизонтальная и вертикальная линейки по умолчанию показывают сантиметры. `rulerUnit="inch"` сохраняет выбор дюймов. Поля и абзацные отступы редактируются средствами движка и экспортируются в `layout` и HTML.
+- `ui.titleBar=false` скрывает строку названия; `renderToolbarEnd` добавляет действия приложения рядом с панелью форматирования.
+- Исправлена потеря отступа первой строки при экспорте DOCX с одновременно заданными `firstLine` и `hanging=0`.
+- В Hujjat геометрия передаётся через существующий `locale.render_profile`; формат серверного API не меняется. Изображения не входят в этот этап.
+
+## 0.1.0-beta.9
+
+- E01: явные `strike=0`, `caps=0` и `vertAlign=baseline` у фрагмента сбрасывают унаследованное оформление. Подчёркивание и зачёркивание разрешаются независимо. Для `caps`/`strike` учитывается различие между переключателями стилей и прямым форматированием.
+- HTML-импорт сохраняет `text-decoration` в Chromium, где CSSOM раскрывает это свойство в longhand-свойства. Простое подчёркивание/зачёркивание больше не вызывает ложные предупреждения о потере стиля.
+- E02: группы абзацев с `page-break-inside:avoid` преобразуются в `keepLines` и связь `keepNext` внутри группы. Вложенные группы не захватывают соседние абзацы; принудительные разрывы страниц имеют приоритет.
+- Непредставимые группы с таблицами дают адресную диагностику `keep-group-not-representable` уровня `loss`. Строгий импорт отклоняется; принятие импорта не разрешает автоматически экспорт отредактированного документа с потерями.
+- Публичные методы и серверный HTML/JSON-контракт не изменены.
+
+## 0.1.0-beta.8
+
+- HTML → DOCX сохраняет шрифт знака абзаца и наследуемый шрифт `<br>`. Обратный экспорт сохраняет семейство и размер знака абзаца отдельно от текста. Авторские пустые строки не удаляются.
+- Нормализация абсолютных интервалов учитывает эффективные размеры Word в половинах пункта, знак абзаца и противоположные смещения фрагментов. Тесный интервал нормализуется при импорте; `line-height-metrics-estimated` явно обозначает отсутствие реальных метрик шрифта в конвертере.
+- `AzHtmlEditor.exportHtml()` возвращает эффективный нормализованный HTML с `changed: true` даже без ручной правки. `dirty` по-прежнему обозначает ручные изменения. Интеграции должны вызывать экспорт перед сохранением независимо от `dirty`.
+- Потеря скрытого знака абзаца при HTML-экспорте диагностируется как `hidden-paragraph-mark-lost` уровня `loss`; его скрытый шрифт не активируется молча.
+- `preserve`, авторские разрывы и сетка таблиц сохраняют прежний контракт. Недостающий во входном HTML шрифт пустых строк библиотека не восстанавливает по первому текстовому фрагменту. Различие Word `exact`/`atLeast` всё ещё требует расширения сохраняемого контракта.
+
+## 0.1.0-beta.7
+
+- Сетка таблицы рассчитывается по ограничениям всех строк одновременно. Пересекающиеся `colspan` больше не зависят от порядка обработки; сохраняются совместимые суммы в неполной сетке, `rowspan` и независимые вложенные таблицы.
+- Безопасные `colgroup`/`col`, частичные колонки и `col span` проходят импорт. Экспорт сохраняет `colgroup` вместе с inline-ширинами фиксированных ячеек; дробные размеры округляются по границам без накопления ошибки.
+- Существенный конфликт явных размеров теперь даёт `table-width-normalized` уровня **loss**, с адресом и численными значениями в twips. Строгий режим требует явного принятия потерь. При конфликте приоритет имеют общая ширина, явные колонки, одиночные и затем объединённые ячейки.
+- Некорректные ширины, объединения и явная DOCX-сетка диагностируются как `table-width-invalid`, `table-span-invalid`, `table-grid-invalid`. Пересечения ячеек, выход за лимиты и непредставимое округление отклоняются контролируемой ошибкой.
+
+Публичные методы и серверный payload не изменены. Интерактивные merge/split
+недоступны в текущем движке `@docx-editor.dev/core@2.27.0`; сохранение уже
+объединённых ячеек проверяется отдельно. Эта правка не подтверждает совпадение
+пагинации или PDF mPDF: для этого требуется приёмка в приложении-потребителе.
+
+## 0.1.0-beta.6
+
+- Исправлена потеря `page-break-*` в Chromium. Поддерживаемые `break-*` приводятся к серверным `page-break-*` с учётом порядка деклараций; `page` соответствует `always`, `avoid-page` — `avoid`.
+- Разрывы на абзацах, контейнерах и до/после таблиц сохраняются после правок и повторного открытия. Смежные правила одного разрыва не создают лишнюю страницу; явные пустые маркеры остаются разрывами.
+- Сохраняются минимальные высоты строк таблиц, `cantSplit`, начальные повторяемые строки шапки и режим `table-layout:auto/fixed`. Ширина таблицы в абсолютных единицах не подгоняется молча под текстовую область.
+- Потеря плавающего размещения таблицы теперь даёт `floating-table-position-lost` уровня `loss`. Строгий HTML-экспорт требует обработки этой диагностики; прямой DOCX-режим не изменён. Правило точной высоты строки диагностируется как `table-row-height-rule-lost`.
+- В адресах диагностик появились необязательные `tableIndex` и `rowIndex` (с нуля, внутри XML-части).
+
+Временный CSSOM/Vite-патч потребителя (`azEditorPaginationCompat`) для beta.4/beta.5 можно
+убрать после установки beta.6 и проверки цикла редактирования. Новый формат метаданных,
+изображения и расширение HTTP-контракта
+в этот этап не входят; отсутствующие во входном HTML сведения не восстанавливаются.
+
+## 0.1.0-beta.5
+
+- `HujjatPage`, `HujjatLocaleContent`, `validateHujjatPage` и `AzHtmlEditor.page`: ориентация A4, шрифт, межстрочный и абзацный интервалы учитываются при открытии.
+- `withHujjatLocale` сохраняет page выбранной локали. HTML-экспорт возвращает page; импорт/экспорт передают общие колонтитулы отдельно от body, включая переменные. Неподдерживаемые варианты требуют принятия потерь.
+- Исправлены боковые padding абзацев/контейнеров; висячий отступ экспортируется в форме padding-left + margin-left:0 для mPDF. Проверены повторные циклы, списки и локальные отступы ячеек.
+- PDF/payload проверяют действующий контракт page. Новые ключи размеров/полей в HTTP не добавляются. Добавлен независимый пример интеграции с page.
+- Бэкенд и приложение-потребитель не изменены. Эталонное сравнение Word PDF / mPDF требует отдельной серверной приёмки.
+
+## 0.1.0-beta.4
+
+- Вложенные HTML-контейнеры сохраняют боковые отступы, висячую первую строку и доступную ширину таблицы. Отступы ячеек остаются локальными.
+- Добавлены `layout`, `AzPageLayout`, `AzLayoutMetadataV1`, `resolveHtmlLayout` и явная политика `lineSpacingPolicy`. Значения по умолчанию совместимы с beta.3; текущие серверные payload не расширены.
+- Численные интервалы можно сохранять с `preserve`; нормализация учитывает крупные фрагменты и вертикальные смещения. Потеря различия exact/atLeast диагностируется.
+- Оба редактора предоставляют `setParagraphPagination`, включая явное выключение наследованных правил и undo.
+- Предупреждения могут содержать адрес, этап и значения до/после. Добавлены `analyzeDocxFormatting`, `onDiagnostics` и состояние ресурсов `status.fonts`.
+- Исправлен цикл уведомлений при inline `onStatusChange`. HTML не сериализуется на каждую клавишу; устаревшие асинхронные результаты не применяются к новому черновику.
+- Добавлены общая инструкция по профилю страницы и пример отдельного хранения HTML и метаданных.
+
+### При обновлении
+
+Табуляция, её позиции, `widowControl` и численное вертикальное смещение теперь сообщаются
+как `loss` при преобразовании в ограниченный HTML. Потребителю нужно показать предупреждения
+и получить решение пользователя перед `allowLossy: true`. Прямое сохранение DOCX эти свойства
+не нормализует. Неподдержанная геометрия и разные разделы не сворачиваются молча в один профиль.
+
+Профиль нестандартной страницы нужно хранить отдельно и согласовать его применение с PDF-сервером.
+Само обновление не меняет mPDF. `fonts.state: ready` не гарантирует одинаковые метрики с Word.
+Численные интервалы `preserve` могут приводить к авторскому наложению строк.
+В локальных замерах открытие до готовности занимало на 46–82 мс больше, чем в исходной
+версии (11–24% на наборах 2/30/60 страниц); ускорение открытия не заявляется.
+Ввод и экспорт в этих замерах не ухудшились. Результаты зависят от окружения и шрифтов.
+Сопоставление фактических серверного HTML/mPDF и эталона Word PDF в этом выпуске не выполнено:
+эталонные данные отсутствуют. Проверки библиотеки не заменяют эту приёмку.

package/README.md

@@ -1,217 +1,74 @@
-# 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
+```
+
+Для воспроизводимой установки версии beta.11:
+
+```sh
+npm install --save-exact @makhmudov.kay/az-editor@0.1.0-beta.11
+```
+
+Требуются 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)
+- [HTML с отдельным хранением геометрии](examples/integration/LayoutDraftExample.tsx)
+- [HTML и серверный page: ориентация, колонтитулы, PDF](examples/integration/ServerPageDraftExample.tsx) — с версии beta.5.
+
+[Геометрия страницы, интервалы и диагностика оформления](docs/layout-metadata-v1.ru.md).
+
+Это исходники для копирования в приложение, а не дополнительные экспорты 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).