@meistrari/minuta-editor 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# @meistrari/minuta-editor
+
+O editor de minuta do **defesa.ai** sem framework: a folha A4 paginada de
+verdade, edição rica, cabeçalho/rodapé, placeholders de variável e export
+DOCX com as mesmas quebras de página do preview. Monta em qualquer app —
+React, Vue, Svelte, vanilla — com uma chamada:
+
+```ts
+import { createMinutaEditor } from '@meistrari/minuta-editor'
+import '@meistrari/minuta-editor/style.css'
+
+const editor = createMinutaEditor(document.getElementById('minuta')!, {
+    html: documento.html,
+    onChange: () => salvar(editor.getHTML()),
+})
+```
+
+**Zero I/O.** Nada de fetch, autosave, histórico ou auth aqui — isso é do
+app que monta. O que entra é HTML; o que sai é HTML e um `Blob` de `.docx`.
+
+É o mesmo motor que o `@meistrari/minuta-nuxt` usa por dentro (o módulo Nuxt
+é uma casca fina sobre este pacote), então o que se edita aqui sai idêntico
+ao que o defesa.ai produz.
+
+## API
+
+```ts
+const editor = createMinutaEditor(el, {
+    html,                                   // documento inicial
+    editable: true,
+    margins: { top: 95, right: 113, bottom: 95, left: 113 }, // px @96dpi (2,5cm / 3cm)
+    header: { logoUrl: null, position: 'left' },
+    chrome: { header: '', footer: '', showPageNumber: true },
+    variables: [...],                       // catálogo → liga o modo template
+    uploadImage: async file => ({ src, vaultSrc }) | null,
+    toolbar: true,                          // false = o host monta a barra dele
+    onReady: tiptap => {},
+    onChange: () => {},
+    onEditChrome: part => {},               // clique no cabeçalho/rodapé
+})
+
+editor.getHTML()          // → string
+editor.exportDocx()       // → Promise<Blob>  (carrega a lib `docx` sob demanda)
+editor.usedVariables()    // → string[]
+editor.setEditable(bool)
+editor.setChrome({ header, footer, headerScope, footerScope, showPageNumber })
+editor.setHeader({ logoUrl, position })
+editor.setVariables(catalogo)
+editor.schedulePaginate() // repagina (após mudar algo que afeta altura por fora)
+editor.totalPages()
+editor.destroy()
+
+editor.tiptap             // a instância do Tiptap — escotilha de fuga
+editor.root / .container / .sheet   // os elementos, para ancorar overlays
+```
+
+### Decisões que vale conhecer
+
+**`exportDocx` devolve `Blob`, não baixa.** Quem decide o nome, se manda pro
+backend ou se abre em outra aba é o host. Um pacote que dispara download
+sozinho toma uma decisão que não é dele.
+
+**`toolbar: false` + `editor.tiptap`.** Um app com design system próprio
+(antd, Material…) monta a barra dele e fala com o Tiptap direto —
+`editor.tiptap.chain().focus().toggleBold().run()`, `isActive('bold')`. É a API
+do Tiptap, documentada, sem um wrapper de comandos que sempre falta um.
+
+**CSS em arquivo, com namespace.** Tudo vive sob `.poc-editor-root`, inclusive
+as utilities atômicas que o defesa.ai tira do UnoCSS. Importe
+`@meistrari/minuta-editor/style.css` uma vez.
+
+**A lib `docx` fica fora do entry principal.** É o maior pedaço do bundle
+(~1 MB) e só serve no clique de exportar: `exportDocx()` faz `import()`
+dinâmico, e quem precisa da função crua importa de
+`@meistrari/minuta-editor/docx`.
+
+## Modo template (placeholders de variável)
+
+Passe o catálogo e o editor vira editor de template: `/` no texto (ou o botão
+`{ }` da barra) abre o seletor, busca pelo rótulo e insere um placeholder.
+
+```ts
+createMinutaEditor(el, {
+    html,
+    variables: [
+        { key: 'PROCESSO', label: 'Nº do Processo', description: 'De info_processos.processo', group: 'Processo' },
+        { key: 'NOME_REU', label: 'Nome do Réu', group: 'Réu' },
+    ],
+})
+editor.usedVariables() // ['PROCESSO', 'NOME_REU']
+```
+
+O placeholder é um **nó atômico** do Tiptap (`<span data-minuta-var="PROCESSO">`),
+não texto: seleciona inteiro, apaga inteiro, formata inteiro. Negritar metade de
+um `#PROCESSO` textual produziria `<b>#PRO</b>CESSO` e a substituição passaria
+reto; com nó, isso não é representável.
+
+Para resolver, `resolveTemplateVariables(html, { PROCESSO: '…' })` (exportado
+daqui) — o que não tem valor continua placeholder vivo no documento.
+
+## React
+
+```tsx
+import { useEffect, useRef } from 'react'
+import { createMinutaEditor, type MinutaEditor } from '@meistrari/minuta-editor'
+import '@meistrari/minuta-editor/style.css'
+
+export function MinutaEditor({ html, onChange }: { html: string, onChange: (html: string) => void }) {
+    const host = useRef<HTMLDivElement>(null)
+    const editor = useRef<MinutaEditor | null>(null)
+
+    useEffect(() => {
+        editor.current = createMinutaEditor(host.current!, {
+            html,
+            onChange: () => onChange(editor.current!.getHTML()),
+        })
+        return () => editor.current?.destroy()
+        // o HTML inicial é lido uma vez: o editor é a fonte da verdade enquanto vive
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+
+    return <div ref={host} style={{ height: '100vh' }} />
+}
+```
+
+## Vue / Nuxt
+
+Use `@meistrari/minuta-nuxt` — ele já embrulha este pacote em componentes
+(`<MinutaEmbed>`, `<MinutaTemplateEditor>`) e traz o proxy de API do defesa.ai.
+
+## Desenvolvimento
+
+```bash
+bun install
+bun run build       # unbuild → dist/
+bun run typecheck
+```
+
+Publicado no npm pelo workflow `Publish @meistrari/minuta-editor`. Como o
+`minuta-nuxt` depende deste pacote pelo npm, **publique este primeiro** quando
+uma mudança atravessar os dois.