@makhmudov.kay/az-editor 0.1.0-beta.2 → 0.1.0-beta.4

package/docs/layout-metadata-v1.ru.md

@@ -0,0 +1,135 @@
+# Геометрия страницы и сохранение оформления
+
+В HTML-режиме библиотека создаёт документ из ограниченного HTML. В прямом DOCX-режиме
+она использует разделы исходного файла. Геометрия HTML не применяется к прямому DOCX.
+
+## Существующий сервер без метаданных
+
+Используйте `<AzHtmlEditor initialHtml={html} />` без `layout`. По умолчанию: A4,
+поля сверху/справа/снизу/слева 15/20/35/20 мм, колонтитулы и gutter — 0.
+В OOXML это 11906 × 16838 twips, поля 850/1134/1984/1134, ширина текста 9638.
+Один twip равен 1/20 pt; один дюйм — 1440 twips.
+
+`createHujjatTemplatePayload` и `requestHujjatPreview` отправляют прежний JSON.
+Новый `layout` не добавляется ими в серверные запросы. Само обновление npm-пакета
+не меняет настройки mPDF и не восстанавливает данные, удалённые серверным импортом.
+
+## Собственная геометрия
+
+```ts
+import { resolveHtmlLayout, type AzHtmlLayoutOptions } from '@makhmudov.kay/az-editor';
+
+export const options: AzHtmlLayoutOptions = {
+  page: {
+    widthTwips: 11910, heightTwips: 16840, orientation: 'portrait',
+    margins: { top: 780, right: 1133, bottom: 280, left: 1133, header: 0, footer: 0, gutter: 0 },
+  },
+  lineSpacingPolicy: 'preserve',
+};
+export const metadata = resolveHtmlLayout(options);
+```
+
+Размеры должны быть конечными положительными целыми числами до 31680 twips (22 дюйма).
+Поля — неотрицательные целые; остаётся положительная область текста с учётом gutter.
+Ориентация должна соответствовать размерам. Некорректный профиль отклоняется.
+`resolveHtmlLayout` возвращает независимую копию с заполненными значениями по умолчанию.
+
+`layout`, как и `initialHtml`, фиксируется при монтировании `AzHtmlEditor`.
+Для другой версии, языка или профиля разрешите вопрос несохранённых правок и задайте новый React `key`.
+Изменение props или вложенного объекта полей не переоткрывает черновик.
+
+## Что возвращает экспорт
+
+`importHujjatTemplate` и HTML-экспорт возвращают необязательный объект:
+
+```ts
+import type { AzLayoutMetadataV1 } from '@makhmudov.kay/az-editor';
+
+export function isLayoutV1(value: unknown): value is AzLayoutMetadataV1 {
+  // Проверка только маршрутизации версии; числа дополнительно проверяет resolveHtmlLayout.
+  return typeof value === 'object' && value !== null &&
+    'schema' in value && value.schema === 'az-editor.layout' &&
+    'version' in value && value.version === 1;
+}
+```
+
+Полная форма: `{ schema: 'az-editor.layout', version: 1, page, lineSpacingPolicy }`.
+Этот объект находится рядом с `html`, `warnings` и `locales`, вне языкового JSON.
+После правок `page` читается из фактически сохранённого DOCX, включая изменения через
+«Параметры страницы». Входной `options.page` не переписывает документ при экспорте.
+
+Без правок `exportHtml()` возвращает исходную строку HTML, `changed: false` и известные
+метаданные импорта, без сохранения и повторного разбора DOCX. `changed` описывает правки
+черновика; приложение отдельно решает, нужно ли впервые сохранить профиль.
+
+Одна версия метаданных описывает одну геометрию. Разные разделы дают `section-normalized`
+с уровнем `loss`; при разной геометрии `layout` отсутствует. Исходные разделы прямого DOCX
+остаются неизменными. Не заменяйте их метаданными одной страницы.
+
+При нестандартной геометрии HTML-экспорт выдаёт `layout-not-carried-by-html`.
+Если сохранить только HTML, геометрия не восстановится при открытии и не попадёт в PDF.
+Пример отдельного хранения: [LayoutDraftExample.tsx](../examples/integration/LayoutDraftExample.tsx).
+
+## Политика интервалов
+
+| Политика | Поведение |
+| --- | --- |
+| `normalize` (по умолчанию) | Множитель меньше 1 увеличивается до 1. При DOCX → HTML тесный абсолютный интервал становится `normal` с предупреждением. Проверяются размеры всех видимых фрагментов и численное вертикальное смещение. |
+| `preserve` | Сохраняет представимые численные значения, включая множители 124/240 и 158/240. Возвращает предупреждение о риске наложения. |
+
+Проверка размера фрагментов — оценка, а не измерение ascent/descent всех шрифтов.
+Большие буквы, формулы, разные начертания и смещения требуют проверки на реальных данных.
+Абсолютный HTML `line-height` импортируется как Word `atLeast`. По CSS невозможно узнать,
+был ли в исходнике `exact`; при DOCX → HTML это различие отмечено `line-rule-lost`.
+Численное `w:position` не сохраняется в действующем HTML-контракте: `baseline-shift-lost`
+имеет уровень `loss`. `w:spacing` сохраняется как `letter-spacing`.
+
+## Диагностика и шрифты
+
+`HujjatWarning` сохраняет `code`, `message`, `severity`. Дополнительные поля:
+`stage` (`import`, `export`, `edit`, `fonts`), `location`, `before`, `after`.
+`location` может содержать `part`, `paragraphIndex`, `runIndex`, `sectionIndex`, `htmlPath`.
+Индексы начинаются с нуля, относятся к одному снимку и не являются постоянными ID.
+
+`onDiagnostics` у обоих компонентов сообщает риски исходного/сохранённого DOCX, не меняя
+его. После правки предыдущая диагностика очищается; новый анализ выполняется при
+явном `save()`. Для самостоятельного анализа есть `analyzeDocxFormatting(bytes)`.
+HTML-экспорт возвращает собственные предупреждения преобразования в результате вызова.
+Полный текст документа в отчёт исходной диагностики не включается.
+
+`status.fonts` содержит `state` и `warnings`. `loading` означает ожидание источников;
+`ready` — источники предоставлены без известных ошибок; `degraded` — известная
+подстановка или ошибка; `unknown` — недостаточно сведений. При загрузке источников
+HTML-черновик остаётся в фазе `loading`. Ошибка шрифта не уничтожает черновик: он может
+перейти в `ready` с `fonts.state: 'degraded'` и предупреждением.
+
+Состояние `ready` не удостоверяет совпадение с Word. Проверяются предоставленные
+источники, таблицы подстановок с weight/style и сообщение движка о недоступных семействах.
+Таблица конфигурации может содержать подстановки для ещё не используемых начертаний.
+Встроенные шрифты и отсутствующие глифы не позволяют считать пустой список доказательством
+точного совпадения. `document.fonts.ready` сам по себе недостаточен для ресурсов движка.
+Передавайте стабильный `fonts`; для замены набора шрифтов разрешите правки и перемонтируйте редактор.
+
+## Управление абзацами
+
+Оба ref предоставляют `setParagraphPagination({ keepNext?, keepLines?, widowControl?, pageBreakBefore? })`.
+Значения boolean применяются к текущему выделению одной командой с undo. `false` явно
+выключает наследованное правило; пропущенное поле не изменяется. Во время загрузки,
+экспорта HTML, `actionsDisabled` или режима `view` команда отклоняется.
+
+Для кнопки используйте `onMouseDown={event => event.preventDefault()}`, чтобы сохранить
+выделение. HTML поддерживает `page-break-before`, `page-break-after`, `page-break-inside`;
+`widowControl` не входит в контракт и при экспорте даёт `widow-control-lost` уровня `loss`.
+Табуляция/позиции/заполнители также дают адресованные `loss`. Приложение должно показать
+их пользователю перед вызовом с `allowLossy: true`; автоматического выравнивания пробелами
+или превращения в таблицы нет.
+
+## Согласование с сервером
+
+Для собственного профиля отдельно согласуйте версию метаданных, хранение рядом с языком
+и версией шаблона, валидацию, применение при preview и финальном PDF, поля колонтитулов,
+шрифты всех начертаний и миграцию старых записей. Имя HTTP-поля здесь не задаётся.
+
+Приёмка: один исходник → серверный HTML → редактор → сохранённый HTML → серверный PDF.
+Проверяйте текст, заголовки и подписи, переносы и страницы на одинаковых шрифтах и полях.
+Без фактического серверного HTML и эталона Word PDF совпадение этой цепочки не проверено.

package/examples/integration/DocxEditorExample.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 import {
   AzDocumentEditor, DOCX_MIME, downloadDocx, readDocxFile,
-  type AzDocumentEditorHandle, type EditorStatus,
+  type AzDocumentEditorHandle, type EditorStatus, type HujjatWarning,
 } from '@makhmudov.kay/az-editor';
 import '@makhmudov.kay/az-editor/styles.css';
 
@@ -18,6 +18,7 @@ export function DocxEditorExample() {
   const [dirty, setDirty] = useState(false);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState('');
+  const [diagnostics,setDiagnostics] = useState<HujjatWarning[]>([]);
 
   useEffect(() => {
     if (!dirty) return;
@@ -82,11 +83,15 @@ export function DocxEditorExample() {
       <span role="status">{busy ? 'Обработка…' : dirty ? 'Есть несохранённые правки' : 'Нет несохранённых правок'} · Страниц: {status.pages}</span>
     </div>
     {(error || status.error) && <p role="alert">{error || status.error}</p>}
+    {[...diagnostics,...(status.fonts?.warnings ?? [])].length > 0 && <details>
+      <summary>Проверка оформления</summary>
+      <ul>{[...diagnostics,...(status.fonts?.warnings ?? [])].map((w,i)=><li key={i}>{w.message}{w.location?.paragraphIndex !== undefined ? ` (абзац ${w.location.paragraphIndex+1})`:''}</li>)}</ul>
+    </details>}
     <AzDocumentEditor key={document.key} ref={editor} document={document.bytes}
       title={document.name} style={{ height: 720 }} mode={busy ? 'view' : 'edit'}
       actionsDisabled={busy || status.loading || !!status.error}
       onOpen={() => input.current?.click()} onSave={() => void save()}
       onChange={() => { revision.current += 1; setDirty(true); }}
-      onStatusChange={setStatus} onFontError={setError} />
+      onStatusChange={setStatus} onFontError={setError} onDiagnostics={setDiagnostics} />
   </section>;
 }

package/examples/integration/HtmlDraft.tsx

@@ -45,6 +45,7 @@ export function HtmlDraft({ initialHtml, variables = [], onApply, onCancel }: Ht
       <button type="button" disabled={status.phase === 'exporting'} onClick={cancel}>Закрыть черновик</button>
     </div>
     {error && <p role="alert">{error}</p>}
+    {!!status.fonts?.warnings.length && <details><summary>Шрифты и переносы</summary><ul>{status.fonts.warnings.map((w,i)=><li key={i}>{w.message}</li>)}</ul></details>}
     {!!status.warnings.length && <details open={status.phase === 'blocked' || !!pending}>
       <summary>Изменения при преобразовании ({status.warnings.length})</summary>
       <ul>{status.warnings.map((w, i) => <li key={i}>{w.message}</li>)}</ul>

package/examples/integration/LayoutDraftExample.tsx

@@ -0,0 +1,39 @@
+import {useRef,useState} from 'react';
+import {AzHtmlEditor,resolveHtmlLayout,type AzHtmlEditorHandle,type AzHtmlEditorStatus,type AzLayoutMetadataV1,type AzHtmlExportResult} from '@makhmudov.kay/az-editor';
+import '@makhmudov.kay/az-editor/styles.css';
+
+export interface StoredDraft { id:string; version:number; locale:string; html:string; layout:AzLayoutMetadataV1 }
+/** The host implements storage after agreeing its metadata contract with the server. */
+export function LayoutDraftExample({draft,onApply}:{draft:StoredDraft;onApply:(result:{html:string;layout:AzLayoutMetadataV1})=>Promise<void>}){
+  return <Session key={`${draft.id}:${draft.version}:${draft.locale}`} draft={draft} onApply={onApply}/>;
+}
+function Session({draft,onApply}:{draft:StoredDraft;onApply:(result:{html:string;layout:AzLayoutMetadataV1})=>Promise<void>}){
+  const ref=useRef<AzHtmlEditorHandle>(null),busy=useRef(false);
+  const [status,setStatus]=useState<AzHtmlEditorStatus>(),[pending,setPending]=useState<AzHtmlExportResult>(),[error,setError]=useState(''),[saving,setSaving]=useState(false);
+  async function apply(result:AzHtmlExportResult){
+    if(busy.current)return;
+    if(!result.layout){setError('Разные разделы не описываются одной геометрией. Требуется отдельное решение.');return;}
+    busy.current=true;setSaving(true);
+    try{await onApply({html:result.html,layout:resolveHtmlLayout(result.layout)});setPending(undefined);}
+    catch(e){setError(String(e));}finally{busy.current=false;setSaving(false);}
+  }
+  async function prepare(){
+    if(busy.current||status?.phase!=='ready')return;
+    try{const result=await ref.current!.exportHtml({allowLossy:true});if(result.warnings.length)setPending(result);else await apply(result);}
+    catch(e){setError(String(e));}
+  }
+  return <section>
+    <button disabled={saving||!!pending||status?.phase!=='ready'} onClick={()=>void prepare()}>Применить HTML и профиль</button>
+    <button disabled={saving||!!pending||status?.phase!=='ready'} onMouseDown={e=>e.preventDefault()} onClick={()=>{try{ref.current!.setParagraphPagination({keepNext:true,keepLines:true});}catch(e){setError(String(e));}}}>
+      Связать абзац со следующим
+    </button>
+    {pending&&<div role="alert"><ul>{pending.warnings.map((w,i)=><li key={i}>{w.message}</li>)}</ul>
+      <button disabled={saving} onClick={()=>void apply(pending)}>Принять указанные изменения</button>
+      <button disabled={saving} onClick={()=>setPending(undefined)}>Вернуться к правкам</button>
+    </div>}
+    {error&&<p role="alert">{error}</p>}
+    {status?.phase==='blocked'&&<button onClick={()=>void ref.current!.acceptImportLoss().catch(e=>setError(String(e)))}>Открыть с потерями: {status.warnings.map(w=>w.message).join(' ')}</button>}
+    <AzHtmlEditor ref={ref} initialHtml={draft.html} layout={draft.layout} onStatusChange={setStatus}
+      mode={pending||saving ? 'view':'edit'} actionsDisabled={!!pending||saving} style={{height:700}}/>
+  </section>;
+}

package/examples/integration/README.md

@@ -10,6 +10,7 @@
 | `HtmlDraft.tsx` | Применение/отмена, подтверждение потерь, переменные |
 | `server-api.ts` | Пример HTTP-контрактов сохранения и PDF |
 | `loadFonts.ts` | Загрузка файлов шрифтов в конфигурацию `fonts` |
+| `LayoutDraftExample.tsx` | Черновик с отдельными метаданными страницы после согласования серверного контракта |
 
 Для `HtmlFormExample` скопируйте и `HtmlDraft`. Остальные примеры независимы.
 Файлы входят в npm-архив как исходники, не как отдельные экспорты пакета.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makhmudov.kay/az-editor",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "type": "module",
   "types": "./dist/library/index.d.ts",
   "sideEffects": [
@@ -17,6 +17,8 @@
   "files": [
     "dist",
     "docs/integration.ru.md",
+    "docs/layout-metadata-v1.ru.md",
+    "CHANGELOG.md",
     "examples/integration",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE"
@@ -48,6 +50,7 @@
   },
   "devDependencies": {
     "@playwright/test": "1.64.0",
+    "@types/jsdom": "^30.0.0",
     "@types/node": "26.6.4",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",