mgcode-docx-editor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MGCODE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# mgcode-docx-editor
+
+Editor WYSIWYG de **templates .docx** feito do zero (contentEditable + `document.execCommand`),
+com a "casca" (toolbar, régua, zoom) em Material UI. Autora um documento com
+cabeçalho/rodapé fixos e corpo com placeholders `{{variavel}}`, e exporta um
+`.docx` válido para o fluxo LibreOffice → PDF.
+
+## Instalação
+
+```bash
+npm install mgcode-docx-editor
+```
+
+Peer dependencies (devem estar instaladas no projeto consumidor): `react`, `react-dom`,
+`@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled`.
+
+## API
+
+```tsx
+import { useRef } from 'react';
+import { DocxEditor, DocxEditorHandle } from 'mgcode-docx-editor';
+
+const editorRef = useRef<DocxEditorHandle>(null);
+
+<DocxEditor
+  ref={editorRef}
+  documentBuffer={documentBuffer ?? undefined}          // importar .docx existente
+  document={documentBuffer ? undefined : documentModel} // ou criar a partir de modelo
+  mode="editing"                                          // 'editing' | 'viewing'
+  showToolbar
+  showRuler
+  showZoomControl
+/>;
+
+// Salvar:
+const buffer = await editorRef.current?.save(); // Promise<ArrayBuffer> (.docx)
+```
+
+### Props (`DocxEditorProps`)
+
+| Prop | Tipo | Descrição |
+| --- | --- | --- |
+| `documentBuffer` | `ArrayBuffer?` | Importa um `.docx` existente. Tem precedência sobre `document`. |
+| `document` | `DocumentModel?` | Cria/edita a partir de um modelo estruturado. |
+| `mode` | `'editing' \| 'viewing'` | Editável ou somente leitura. |
+| `showToolbar` | `boolean?` | Exibe a barra de ferramentas. |
+| `showRuler` | `boolean?` | Exibe a régua funcional. |
+| `showZoomControl` | `boolean?` | Exibe o controle de zoom. |
+
+### Handle imperativo (`DocxEditorHandle`, via `ref`)
+
+- `save(): Promise<ArrayBuffer>` — serializa o conteúdo atual para `.docx`.
+- `getModel(): DocumentModel` — retorna o modelo atual (`header`/`body`/`footer`/`variables`).
+
+### `DocumentModel`
+
+```ts
+interface DocumentModel {
+  header?: string;      // HTML do cabeçalho fixo (ex.: logo)
+  body: string;         // HTML do corpo (contém {{variaveis}})
+  footer?: string;      // HTML do rodapé fixo
+  variables?: string[]; // nomes para o menu "Inserir variável"
+}
+```
+
+## Arquitetura
+
+- **Editor**: três regiões `contentEditable` (header/body/footer) + `execCommand`.
+- **Página**: **A4** (794×1123 px a 96dpi na tela; 11906×16838 twips no export,
+  via `PAGE_SIZE_A4_TWIPS` em `docx/generate.ts`).
+- **Exportação** (`save()`): `@turbodocx/html-to-docx` (MIT) converte o HTML das
+  regiões em `.docx`, com cabeçalho/rodapé como partes do Word e margens da régua
+  como `w:pgMar`. Ver `docx/generate.ts`.
+- **Importação** (`documentBuffer`): `mammoth` (BSD-2) converte o `.docx` em HTML.
+  Ver `docx/importDocx.ts`.
+- **Régua**: arrasta margens de página (→ margens da seção do `.docx`) e recuos de
+  parágrafo. Conversões px↔twips em `docx/units.ts`.
+
+### Polyfill de `Buffer` (imagens no browser)
+
+O bundle browser da `@turbodocx/html-to-docx` usa o global `Buffer` do Node para
+decodificar imagens base64; CRA/webpack 5 não polyfilla globais do Node, o que
+causava `"Buffer is not defined"` ao salvar documentos com imagens. Correção:
+dependência `buffer` (feross/buffer, MIT) e `ensureBufferGlobal()` chamado no
+início de `modelToDocx()` em `docx/generate.ts` — atribui `globalThis.Buffer` ao
+polyfill se indefinido. É feito em tempo de chamada (não de import), então
+funciona independentemente da ordem de carregamento e não sobrescreve um
+`Buffer` já existente (Node/Jest).
+
+### Paginação visual (estilo Word)
+
+O editor renderiza N caixas "papel" A4 posicionadas absolutamente
+(`data-page-index` em cada uma, para testes/automação), mas o corpo continua
+sendo **um único `contentEditable` contínuo** atravessando todas as páginas —
+o DOM nunca é dividido, então cursor, undo e `execCommand` seguem funcionando.
+
+```
+┌─ página 0 ──────────────┐
+│ header REAL (editável)  │  ← 48px da borda (distância do Word)
+│ corpo contínuo…         │
+│ footer REAL (editável)  │
+├─ gap 24px ──────────────┤
+┌─ página 1+ ─────────────┐
+│ espelho header (RO)     │  ← aria-hidden, dangerouslySetInnerHTML
+│ …corpo continua         │     sincronizado a cada input
+│ espelho footer (RO)     │
+└─────────────────────────┘
+```
+
+- **Quebra por bloco**: `docx/pagination.ts` (módulo puro, sem DOM no cálculo).
+  `computePageLayout(blocks, {usableHeightPx, interPageGapPx})` decide, para cada
+  bloco top-level do corpo, se ele cruzaria a zona do rodapé; se sim (e couber
+  inteiro numa página), um **espaçador** não-editável é inserido antes dele
+  (`createSpacerElement()`: div com `data-page-spacer`, `contenteditable=false`),
+  empurrando-o para a próxima página.
+- **Contrato de coordenadas**: `BlockBox.top` é em coordenadas **sem
+  espaçadores**; a medição do DOM em `DocxEditor.tsx` subtrai a altura acumulada
+  dos espaçadores acima de cada bloco antes de chamar `computePageLayout`.
+- **Recomputação**: a cada input, mudança de margens/régua, import de `.docx` e
+  `load` de imagem (listener em fase de captura), com throttle via
+  `requestAnimationFrame` (`schedulePagination`). O ciclo é auto-corrigível:
+  remove todos os espaçadores e reinsere do zero.
+- **Header/footer editáveis** vivem apenas na página 1, nas áreas de margem;
+  páginas 2+ mostram espelhos somente leitura sincronizados a cada edição.
+- **Sem rastro no modelo**: `buildModel()`/`save()` removem os espaçadores via
+  `stripPageSpacers()` — a paginação é puramente visual e o round-trip do HTML
+  do corpo é exato (há teste para isso).
+
+### Indicador de região em edição (estilo Word)
+
+`DocxEditor.tsx` mantém o estado `focusedRegion: 'header' | 'body' | 'footer' | null`
+(atualizado em `onRegionFocus`/`onRegionBlur`):
+
+- Ao focar o **cabeçalho ou rodapé**, a região ganha contorno tracejado
+  (`outline: 1px dashed`, cor primária) + etiqueta `Chip` MUI ("Cabeçalho"/"Rodapé"),
+  e o **corpo esmaece** (`opacity: 0.45`, via a flag derivada `editingChrome`).
+- Ao editar o **corpo**, header/footer reais e os espelhos das páginas 2+ esmaecem
+  levemente (`opacity: 0.55`).
+
+É indicação puramente visual — não altera modelo nem exportação.
+
+### Variáveis `{{...}}`
+
+São inseridas como **texto literal contíguo** (via Range API, não `execCommand`),
+garantindo que o LibreOffice/docxtemplater consiga substituí-las — o token nunca é
+quebrado entre runs do Word. Há teste dedicado para isso em
+`docx/__tests__/generate.test.ts`.
+
+### Campos de página do Word (`[[PAGINA]]` / `[[TOTAL_PAGINAS]]`)
+
+Módulo `docx/pageFields.ts`. O usuário insere **tokens literais** `[[PAGINA]]` e
+`[[TOTAL_PAGINAS]]` que, na exportação, viram campos nativos do Word
+(PAGE/NUMPAGES) que o Word/LibreOffice atualizam sozinhos.
+
+- **Sintaxe `[[...]]` é deliberada**: diferente de `{{...}}` para o docxtemplater
+  **nunca** tentar substituí-los no pipeline.
+- **Inserção**: menu "Variável" da toolbar (agora **sempre visível**, mesmo sem
+  `variables`), itens "Nº da página" e "Total de páginas" → prop
+  `onInsertPageField` do `Toolbar.tsx` → `handleInsertPageField` em
+  `DocxEditor.tsx`, que insere via Range API (contíguo, como as variáveis).
+  Sem região focada, o fallback é o **rodapé** (onde campos de página fazem sentido).
+- **Exportação** (`modelToDocx` em `docx/generate.ts`): se `hasPageFieldTokens()`
+  detecta tokens no header/footer do modelo, o `.docx` gerado pela lib é
+  pós-processado com **JSZip**: em cada `word/header*.xml` e `word/footer*.xml`,
+  `injectPageFields()` substitui cada token por
+  `<w:fldSimple w:instr=" PAGE ">` / `" NUMPAGES "`. Sem tokens, o buffer sai
+  intacto (nenhum reprocessamento do zip).
+- **Processamento run a run** (invariante crítico): `injectPageFields()` itera
+  o XML com `RUN_PATTERN`, que casa **um `<r>…</r>` inteiro por vez** — o lazy
+  até o primeiro `</r>` nunca atravessa runs vizinhos, porque runs não aninham
+  em OOXML. Cada run com token é reconstruído por `rebuildRun()` +
+  `splitTextByTokens()` como uma sequência ordenada de runs de texto e
+  `fldSimple`, copiando o `rPr` original para dentro de cada pedaço — a
+  formatação (negrito, fonte etc.) é preservada. **Por que run a run**: a
+  implementação antiga usava um único regex sobre o XML inteiro cujo grupo
+  lazy do `rPr` podia "esticar" por cima de runs vizinhos quando havia um run
+  anterior com formatação não vazia — o resultado era XML embaralhado
+  (`fldSimple` aninhado, texto duplicado) e o Word **recusava o arquivo**. Há
+  teste de regressão dedicado em `docx/__tests__/pageFields.test.ts`.
+- **Dois formatos de OOXML**: `RUN_PATTERN`/`rebuildRun()` aceitam XML
+  prefixado (`<w:r>`, como no document.xml) **e** em namespace default sem
+  prefixo (`<r>`, formato dos header/footer gerados pela
+  `@turbodocx/html-to-docx`). No caso sem prefixo, o `fldSimple` declara
+  `xmlns:w` no próprio elemento, exigido pelo atributo `w:instr`.
+- **Valor em cache**: o campo carrega o texto "1", exibido até o Word/LibreOffice
+  atualizar os campos.
+- **Preview no editor**: nos espelhos das páginas 2+, `withPagePreview()` em
+  `DocxEditor.tsx` troca os tokens pelos números reais ("Página 2 de 3"); na
+  página 1 (regiões editáveis) os tokens ficam visíveis como texto.
+
+### Redimensionamento de imagens
+
+Implementado em `DocxEditor.tsx` (estado `selectedImg` + `frame`), sem tocar no
+`execCommand`:
+
+- **Seleção**: delegação de clique na coluna de páginas (`handleColumnClick`) —
+  clicar num `<img>` dentro de qualquer região `contentEditable` seleciona a
+  imagem; clicar fora deseleciona. Em `mode="viewing"` não há seleção.
+- **Moldura**: uma overlay absoluta sobre a coluna de páginas
+  (`data-testid="image-resize-frame"`) com 4 alças de canto
+  (`data-testid="image-resize-handle"`). `updateFrame()` posiciona a moldura a
+  partir de `getBoundingClientRect()` da imagem, **dividindo pelo zoom** (a
+  coluna é escalada via `transform: scale`, mas a overlay vive em coordenadas
+  sem zoom). A moldura tem `pointer-events: none`; só as alças são interativas.
+- **Drag** (`startResize`): durante o arraste só a **largura** é gravada
+  (`style.width` em px, `height: auto` mantém a proporção); o delta do mouse é
+  compensado pelo zoom e a largura é limitada entre 20px e a largura da região.
+  No `mouseup`, a altura é **fixada em px** (`style.height`) e
+  `handleContentChanged()` dispara repaginação + sincronização dos espelhos.
+- **Caminho até o `.docx`**: a exportação (`@turbodocx/html-to-docx`) lê o
+  `style="width/height"` em px da imagem e converte px→EMU (1px = 9525 EMU) no
+  `wp:extent` — o tamanho redimensionado vai para o arquivo. Há teste de
+  caracterização em `docx/__tests__/generate.test.ts`.
+- **Deseleção automática**: ao clicar fora, ao reimportar um `.docx`
+  (`docVersion` muda) ou se a imagem sair do DOM (`img.isConnected` é checado
+  em `updateFrame()`); a moldura também é reposicionada quando layout, margens
+  ou espelhos mudam.
+
+## Licenças das dependências (todas permissivas / uso comercial livre)
+
+- `@turbodocx/html-to-docx` — MIT
+- `mammoth` — BSD-2-Clause
+- `@mui/material` / `@mui/icons-material` — MIT
+- `buffer` (feross/buffer, polyfill do global `Buffer`) — MIT
+- `jszip` (pós-processamento dos campos de página no `.docx`) — MIT
+
+## Limitações conhecidas (v1)
+
+- `document` e `documentBuffer` são valores **iniciais** (componente não controlado,
+  como editores em geral). Trocar essas props depois de montado **não** re-sincroniza
+  o conteúdo já editado, exceto por um novo `documentBuffer` (que dispara reimportação).
+- Import de `.docx` externo via `mammoth` recupera apenas o **corpo**; cabeçalho e
+  rodapé de arquivos de terceiros não são reconstruídos. Para templates criados por
+  este editor, o `DocumentModel` é a fonte de verdade.
+- `document.execCommand` é depreciado (porém suportado em todos os browsers atuais);
+  é a escolha deliberada para um editor "do zero" sem framework de edição.
+- Colar conteúdo do Word ainda não é sanitizado (escopo futuro).
+- **Paginação por bloco apenas**: um parágrafo nunca é dividido no meio entre
+  páginas — o bloco inteiro é empurrado. Blocos mais altos que a área útil de
+  uma página **não** são divididos e transbordam sobre a página seguinte.
+- Os espelhos de cabeçalho/rodapé nas páginas 2+ são somente leitura; a edição
+  acontece nas regiões reais da página 1.
+
+## Testes
+
+- `docx/__tests__/units.test.ts` — conversões de unidade.
+- `docx/__tests__/generate.test.ts` — `.docx` válido, texto/variável preservados,
+  header/footer, contiguidade do `{{token}}`, imagem base64 → `word/media`,
+  `w:pgSz` A4, `save()` funciona com `globalThis.Buffer` removido (polyfill),
+  tokens `[[PAGINA]]`/`[[TOTAL_PAGINAS]]` viram `fldSimple` PAGE/NUMPAGES no
+  footer (sem tokens vazados), documento sem tokens sai intacto, e
+  caracterização do `wp:extent`: `style="width/height"` em px na imagem vira
+  EMU no `.docx` (1px = 9525 EMU).
+- `docx/__tests__/pageFields.test.ts` — `injectPageFields()`: divisão do run
+  preservando texto ao redor e `rPr`, múltiplos tokens no mesmo run, XML com e
+  sem prefixo `w:` (declaração de `xmlns:w`), XML sem tokens inalterado,
+  `hasPageFieldTokens()`, e **regressão do docx corrompido**: "não embaralha o
+  XML quando há run anterior com formatação" (o regex antigo atravessava runs
+  e gerava `fldSimple` aninhado/texto duplicado).
+- `docx/__tests__/pagination.test.ts` — `computePageLayout` (quebras, espaçadores,
+  blocos maiores que a página, contagem de páginas).
+- `docx/__tests__/importDocx.test.ts` — round-trip de importação.
+- `__tests__/DocxEditor.test.tsx` — `save()`, render, inserção de variável, modo
+  leitura, `getModel()` remove espaçadores com round-trip exato do corpo,
+  etiqueta de foco (Chip "Cabeçalho"/"Rodapé" ao focar a região), inserção dos
+  campos de página pelo menu "Variável", seleção de imagem (clique mostra a
+  moldura com 4 alças; clique fora deseleciona).
+
+A formatação via `execCommand`, o arraste da régua e a paginação visual
+(múltiplas páginas, rodapé ancorado no pé da página, salvar com imagem sem erro
+de `Buffer`) são validados em **browser real** via script Playwright, pois o
+jsdom não implementa `execCommand` nem layout real. Também validados no browser:
+etiquetas e esmaecimento de foco, preview "Página 2 de 2" nos espelhos,
+`fldSimple` no `footer.xml` do `.docx` salvo (1 PAGE + 1 NUMPAGES, runs
+balanceados, sem aninhamento — todas as partes XML do zip validadas com parser
+rigoroso .NET) e o drag de resize de imagem ponta a ponta (arrastar a alça
+altera a largura e o `wp:extent` exportado corresponde ao tamanho arrastado).

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+import * as react from 'react';
+
+interface DocumentModel {
+    /** HTML do cabeçalho fixo (ex.: logo). Opcional. */
+    header?: string;
+    /** HTML do corpo do documento. Contém os placeholders {{variavel}}. */
+    body: string;
+    /** HTML do rodapé fixo. Opcional. */
+    footer?: string;
+    /** Nomes de variáveis disponíveis para inserir (ex.: ["patientName"]). */
+    variables?: string[];
+}
+/** Margens da página em twips (1/1440 pol), como o Word/OOXML espera. */
+interface PageMarginsTwips {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+type DocxEditorMode = 'editing' | 'viewing';
+interface DocxEditorProps {
+    /** Importa um .docx existente (tem precedência sobre `document`). */
+    documentBuffer?: ArrayBuffer;
+    /** Cria/edita a partir de um modelo estruturado. */
+    document?: DocumentModel;
+    mode: DocxEditorMode;
+    showToolbar?: boolean;
+    showRuler?: boolean;
+    showZoomControl?: boolean;
+}
+interface DocxEditorHandle {
+    /** Serializa o conteúdo atual para um .docx (ArrayBuffer). */
+    save(): Promise<ArrayBuffer>;
+    /** Retorna o modelo atual do editor. */
+    getModel(): DocumentModel;
+}
+
+declare const DocxEditor: react.ForwardRefExoticComponent<DocxEditorProps & react.RefAttributes<DocxEditorHandle>>;
+
+export { type DocumentModel, DocxEditor, type DocxEditorHandle, type DocxEditorMode, type DocxEditorProps, type PageMarginsTwips };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import * as react from 'react';
+
+interface DocumentModel {
+    /** HTML do cabeçalho fixo (ex.: logo). Opcional. */
+    header?: string;
+    /** HTML do corpo do documento. Contém os placeholders {{variavel}}. */
+    body: string;
+    /** HTML do rodapé fixo. Opcional. */
+    footer?: string;
+    /** Nomes de variáveis disponíveis para inserir (ex.: ["patientName"]). */
+    variables?: string[];
+}
+/** Margens da página em twips (1/1440 pol), como o Word/OOXML espera. */
+interface PageMarginsTwips {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+type DocxEditorMode = 'editing' | 'viewing';
+interface DocxEditorProps {
+    /** Importa um .docx existente (tem precedência sobre `document`). */
+    documentBuffer?: ArrayBuffer;
+    /** Cria/edita a partir de um modelo estruturado. */
+    document?: DocumentModel;
+    mode: DocxEditorMode;
+    showToolbar?: boolean;
+    showRuler?: boolean;
+    showZoomControl?: boolean;
+}
+interface DocxEditorHandle {
+    /** Serializa o conteúdo atual para um .docx (ArrayBuffer). */
+    save(): Promise<ArrayBuffer>;
+    /** Retorna o modelo atual do editor. */
+    getModel(): DocumentModel;
+}
+
+declare const DocxEditor: react.ForwardRefExoticComponent<DocxEditorProps & react.RefAttributes<DocxEditorHandle>>;
+
+export { type DocumentModel, DocxEditor, type DocxEditorHandle, type DocxEditorMode, type DocxEditorProps, type PageMarginsTwips };