From 1c03ec168c82dd89f900c16a54b296fb89b946c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=9A=D1=83=D1=80=D0=BD=D0=B0=D1=82=20=D0=90=D0=BD=D0=B4?=
 =?UTF-8?q?=D1=80=D0=B5=D0=B9?= <sevenhill@live.ru>
Date: Tue, 2 Jun 2026 06:37:49 +0300
Subject: [PATCH] Support QWord Heading 3 DOCX roundtrip

---
 README.md                       |  2 +-
 src/features/qword/QWord.tsx    |  1 +
 src/io/wordOffice.test.ts       | 10 ++++++++++
 src/io/wordOffice.ts            | 30 +++++++++++++++++++++++++-----
 src/io/wordOfficeImport.test.ts |  9 +++++++++
 5 files changed, 46 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index d19c375..7afb9c0 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ npm run build
 
 ## Поддержка форматов
 
-- QWord открывает `.docx` и сохраняет `.docx`; при импорте базовых DOCX-абзацев читает выравнивание, отступы `w:ind`, переносы строк, разрывы страниц, табуляцию, закладки, внешние и внутренние гиперссылки-якоря, маркированные и нумерованные списки через `w:numPr`/`numbering.xml`, простые таблицы, базовые растровые изображения, явные цвета текста, подсветку, размер и семейство шрифта из OOXML, а при экспорте DOCX сохраняются заголовки, абзацы, переносы строк, разрывы страниц, табуляция, выравнивание и отступы абзацев из HTML `margin-left`/`text-indent`, закладки из HTML `id`, списки, простые таблицы, внешние и внутренние гиперссылки-якоря, базовые растровые изображения и базовое inline-форматирование текста: полужирный, курсив, подчеркивание, зачеркивание, цвет текста, подсветка, размер и семейство шрифта.
+- QWord открывает `.docx` и сохраняет `.docx`; при импорте базовых DOCX-абзацев читает заголовки Word `Heading 1`/`Heading 2`/`Heading 3`, выравнивание, отступы `w:ind`, переносы строк, разрывы страниц, табуляцию, закладки, внешние и внутренние гиперссылки-якоря, маркированные и нумерованные списки через `w:numPr`/`numbering.xml`, простые таблицы, базовые растровые изображения, явные цвета текста, подсветку, размер и семейство шрифта из OOXML, а при экспорте DOCX сохраняются заголовки HTML `h1`/`h2`/`h3`, абзацы, переносы строк, разрывы страниц, табуляция, выравнивание и отступы абзацев из HTML `margin-left`/`text-indent`, закладки из HTML `id`, списки, простые таблицы, внешние и внутренние гиперссылки-якоря, базовые растровые изображения и базовое inline-форматирование текста: полужирный, курсив, подчеркивание, зачеркивание, цвет текста, подсветка, размер и семейство шрифта.
 - QExcell открывает `.xlsx` и сохраняет `.xlsx`; сетка расширяется по фактически заполненным ячейкам, поддерживает несколько листов, скрытые и veryHidden листы через `sheet state`, закрепленные области через `sheetViews pane`, скрытие сетки через `sheetView showGridLines`, масштаб листа через `sheetView zoomScale`, автофильтр через `autoFilter ref`, область печати через `_xlnm.Print_Area`, цвет вкладки листа через `sheetPr tabColor`, ширину и скрытие колонок через `cols/col width` и `col hidden`, высоту и скрытие строк через `row ht/customHeight` и `row hidden`, управление скрытием выбранной строки и столбца в интерфейсе, активный лист через `workbookView activeTab`, формулы за пределами стартового диапазона A-H, shared formulas XLSX с относительными ссылками, базовые merged cells, внешние и внутренние гиперссылки ячеек, legacy-заметки ячеек через `comments.xml` и VML `legacyDrawing`, базовые диаграммы листа и базовое форматирование ячеек: полужирный, курсив, подчеркивание, зачеркивание, размер и семейство шрифта, прямые RGB/theme/indexed цвета текста с учетом `xl/theme/theme1.xml`, заливку, горизонтальное и вертикальное выравнивание, перенос текста, границы и цвет границ ячеек, числовые форматы XLSX для дат, процентов, денежных и дробных значений.
 - QPowerPoint открывает `.pptx` и сохраняет `.pptx`; импорт учитывает порядок слайдов из `presentation.xml`, переносы абзацев и ручные переносы строк `a:br` внутри текстовых блоков, маркированные и нумерованные списки подзаголовка через `a:buChar`/`a:buAutoNum`, внешние ссылки текста заголовка/подзаголовка и изображений через `a:hlinkClick` и hyperlink relationships, скрытые слайды через атрибут `show`, переходы `p:transition` для `fade`/`push`/`wipe`, а также заметки докладчика через relationships слайда, сохраняет скрытые слайды, переходы слайдов, заметки докладчика, внешние ссылки текста заголовка/подзаголовка и изображений, базовые растровые изображения слайдов, пользовательский цвет фона слайда, списки подзаголовка, а также цвет, размер и семейство шрифта текста заголовка/подзаголовка.
 - QOutlook открывает `.eml` и одиночные сообщения Outlook `.msg`, сохраняет письма в `.eml`; импорт EML поддерживает простые текстовые письма, `multipart/alternative`, `multipart/mixed`, `multipart/related`, `text/plain`, fallback из `text/html` в читаемый текст, base64, quoted-printable, MIME encoded-word заголовки UTF-8/windows-1251, MIME-вложения и inline-вложения с `Content-ID`, `To`, `Cc`, `Bcc`, `Reply-To`, `Message-ID`, `In-Reply-To`, `References`, `Importance`, `X-Priority` и `Priority`. Импорт MSG читает тему, отправителя, получателей `To/Cc/Bcc`, `Reply-To`, `Message-ID`, `In-Reply-To`, `References`, `Importance`, `X-Priority` и `Priority` из транспортных заголовков, текст/HTML body и вложения, если эти поля доступны в MSG-файле. Новые письма можно адресовать через `To/Cc/Bcc`, задавать `Reply-To` и сохранять в EML вместе с добавленными файлами. `.pst` и экспорт в `.msg` пока не реализованы.
diff --git a/src/features/qword/QWord.tsx b/src/features/qword/QWord.tsx
index d58a835..8d16ec5 100644
--- a/src/features/qword/QWord.tsx
+++ b/src/features/qword/QWord.tsx
@@ -128,6 +128,7 @@ const styleGalleryOptions = [
   { value: "p", label: "Обычный" },
   { value: "h1", label: "Заголовок 1" },
   { value: "h2", label: "Заголовок 2" },
+  { value: "h3", label: "Заголовок 3" },
   { value: "blockquote", label: "Цитата" }
 ];
 
diff --git a/src/io/wordOffice.test.ts b/src/io/wordOffice.test.ts
index eae6344..12272ef 100644
--- a/src/io/wordOffice.test.ts
+++ b/src/io/wordOffice.test.ts
@@ -10,6 +10,7 @@ describe("wordOffice helpers", () => {
     const blocks = htmlToWordBlocks(`
       <h1>План проекта</h1>
       <h2>Задачи</h2>
+      <h3>Контроль качества</h3>
       <p>Первый абзац.</p>
       <ul><li>Подготовить документ</li><li>Проверить таблицу</li></ul>
     `);
@@ -17,6 +18,7 @@ describe("wordOffice helpers", () => {
     expect(blocks).toEqual([
       { type: "heading", level: 1, text: "План проекта", runs: [{ text: "План проекта" }] },
       { type: "heading", level: 2, text: "Задачи", runs: [{ text: "Задачи" }] },
+      { type: "heading", level: 3, text: "Контроль качества", runs: [{ text: "Контроль качества" }] },
       { type: "paragraph", text: "Первый абзац.", runs: [{ text: "Первый абзац." }] },
       {
         type: "list",
@@ -179,6 +181,14 @@ describe("wordOffice helpers", () => {
     expect(documentXml).toMatch(/<w:t[^>]*>Line 1<\/w:t>[\s\S]*<w:br\/>[\s\S]*<w:t[^>]*>Line 2<\/w:t>/);
   });
 
+  it("записывает h3 как стиль Heading3 в XML экспортированного DOCX", async () => {
+    const blob = await exportDocxBlob("Заголовок3.docx", "<h3>Подраздел</h3>");
+    const zip = await JSZip.loadAsync(await blob.arrayBuffer());
+    const documentXml = await zip.file("word/document.xml")?.async("string");
+
+    expect(documentXml).toMatch(/<w:pStyle\b[^>]*w:val="Heading3"[^>]*\/>/);
+  });
+
   it("записывает HTML-разрывы страниц как w:br w:type page в XML экспортированного DOCX", async () => {
     const blob = await exportDocxBlob("Разрыв.docx", '<p>Before<span data-qoffice-page-break="true"></span>After</p>');
     const zip = await JSZip.loadAsync(await blob.arrayBuffer());
diff --git a/src/io/wordOffice.ts b/src/io/wordOffice.ts
index 07a1069..c84b45c 100644
--- a/src/io/wordOffice.ts
+++ b/src/io/wordOffice.ts
@@ -40,7 +40,7 @@ export interface WordParagraphIndent {
 }
 
 export type WordBlock =
-  | { type: "heading"; level: 1 | 2; text: string; runs: WordInlineRun[]; alignment?: WordParagraphAlignment; indent?: WordParagraphIndent; bookmark?: string }
+  | { type: "heading"; level: 1 | 2 | 3; text: string; runs: WordInlineRun[]; alignment?: WordParagraphAlignment; indent?: WordParagraphIndent; bookmark?: string }
   | { type: "paragraph"; text: string; runs: WordInlineRun[]; alignment?: WordParagraphAlignment; indent?: WordParagraphIndent; bookmark?: string }
   | { type: "list"; ordered: boolean; items: WordListItem[] }
   | { type: "table"; rows: string[][] }
@@ -110,7 +110,8 @@ type DocxListInfo = { ordered: boolean; level: number; key: string };
 const mammothStyleMap = [
   "p[style-name='Title'] => h1:fresh",
   "p[style-name='Heading 1'] => h1:fresh",
-  "p[style-name='Heading 2'] => h2:fresh"
+  "p[style-name='Heading 2'] => h2:fresh",
+  "p[style-name='Heading 3'] => h3:fresh"
 ];
 const xmlParserOptions = {
   ignoreAttributes: false,
@@ -238,7 +239,7 @@ export function htmlToWordBlocks(html: string): WordBlock[] {
       return;
     }
 
-    if (tagName === "h1" || tagName === "h2") {
+    if (tagName === "h1" || tagName === "h2" || tagName === "h3") {
       const runs = elementInlineRuns(node);
       const text = inlineRunsText(runs);
       const alignment = paragraphAlignmentFromElement(node);
@@ -247,7 +248,7 @@ export function htmlToWordBlocks(html: string): WordBlock[] {
       if (text) {
         blocks.push({
           type: "heading",
-          level: tagName === "h1" ? 1 : 2,
+          level: headingLevelFromTagName(tagName),
           text,
           runs,
           ...(alignment ? { alignment } : {}),
@@ -299,7 +300,7 @@ function wordBlockToDocxChildren(block: WordBlock, docx: DocxModule) {
     const children = wordInlineRunsToTextRuns(block.runs, docx);
     return [
       new docx.Paragraph({
-        heading: block.level === 1 ? docx.HeadingLevel.HEADING_1 : docx.HeadingLevel.HEADING_2,
+        heading: docxHeadingLevel(block.level, docx),
         spacing: { after: 160 },
         ...docxAlignmentOption(block.alignment, docx),
         ...docxIndentOption(block.indent),
@@ -381,6 +382,22 @@ export function wordInlineRunsToTextRunOptions(runs: WordInlineRun[]) {
   return runs.map(wordInlineRunToTextRunOption);
 }
 
+function headingLevelFromTagName(tagName: string): 1 | 2 | 3 {
+  if (tagName === "h3") {
+    return 3;
+  }
+
+  return tagName === "h2" ? 2 : 1;
+}
+
+function docxHeadingLevel(level: 1 | 2 | 3, docx: DocxModule) {
+  if (level === 3) {
+    return docx.HeadingLevel.HEADING_3 ?? docx.HeadingLevel.HEADING_2;
+  }
+
+  return level === 1 ? docx.HeadingLevel.HEADING_1 : docx.HeadingLevel.HEADING_2;
+}
+
 function wordInlineRunToTextRunOption(run: WordInlineRun) {
   const options: Record<string, unknown> = { text: run.text };
   if (run.bold) {
@@ -1005,6 +1022,9 @@ function docxParagraphTagName(properties: XmlRecord) {
   if (["heading2", "heading 2"].includes(styleValue)) {
     return "h2";
   }
+  if (["heading3", "heading 3"].includes(styleValue)) {
+    return "h3";
+  }
 
   return "p";
 }
diff --git a/src/io/wordOfficeImport.test.ts b/src/io/wordOfficeImport.test.ts
index 67c3d6f..5a55f12 100644
--- a/src/io/wordOfficeImport.test.ts
+++ b/src/io/wordOfficeImport.test.ts
@@ -5,6 +5,15 @@ const tinyPngBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42
 const tinyPngDataUri = `data:image/png;base64,${tinyPngBase64}`;
 
 describe("wordOffice DOCX import", () => {
+  it("imports DOCX Heading 3 as h3", async () => {
+    const blob = await exportDocxBlob("Heading3.docx", "<h3>Quality gate</h3>");
+    const file = new File([blob], "Heading3.docx", { type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document" });
+    const imported = await importDocxFile(file);
+
+    expect(imported.html).toContain("<h3>Quality gate</h3>");
+    expect(htmlToWordBlocks(imported.html)).toEqual([{ type: "heading", level: 3, text: "Quality gate", runs: [{ text: "Quality gate" }] }]);
+  });
+
   it("imports DOCX text color and highlight from OOXML", async () => {
     const blob = await exportDocxBlob(
       "Color.docx",