@meistrari/minuta-react 1.1.0 → 1.3.0

package/README.md

@@ -35,6 +35,8 @@ um `Blob` de `.docx`. Buscar o documento, persistir a edição e baixar o arquiv
 | `chrome` | — | `{ header, footer, headerScope, footerScope, showPageNumber }` |
 | `variables` | — | catálogo `{ key, label, description?, group? }[]` → liga o modo template |
 | `uploadImage` | — | `(file) => Promise<{ src, vaultSrc } \| null>` |
+| `imageFallback` | `'dataUri'` | `'none'` = upload falhou → não insere nada, só `onImageUploadError` |
+| `onImageUploadError` | — | `(error, file) => void` |
 | `toolbar` | `true` | `false` = você monta a sua sobre `ref.current.tiptap` |
 | `blockClickWhileEditing` | `false` | dispara `onBlockClick` também em edição (padrão: só em leitura) |
 | `onChange` | — | `(html) => void`, a cada edição |
@@ -80,26 +82,40 @@ Tudo pelo seu backend, com `x-api-key` + `x-org-id` — seus usuários não prec
 de conta no defesa.ai:
 
 ```
-GET   /data/case/:id/html                         → { html, chrome, margins, source, editionId }
-POST  /data/case/:id/editions { name, html }      → cria a edição (o documento lapidado)
-PATCH /data/case/:id/editions/:editionId { html } → salva (versão automática)
-POST  /data/case/:id/docx                         → .docx do estado atual (a edição, se existir)
+GET   /data/case/:id/html                    → { html, chrome, margins, source, editionId, variablesMarked, markedVariables }
+POST  /data/case/:id/editions { name, html } → cria a edição → { id, updatedAt, contentHash, … }
+PATCH /data/case/:id/editions/:id            → salva → { updatedAt, updatedBy, contentHash, … }
+      { html, baseUpdatedAt }                  400 sem o token; 409 se outro salvou antes
+GET   /data/case/:id/editions                → [{ id, updatedAt, updatedBy, contentHash, … }] sem html
+POST  /data/case/:id/editions/:id/versions   → marco no histórico (o PATCH NÃO cria versão)
+      { comment?, baseUpdatedAt? }             com baseUpdatedAt: 409 se a revisão mudou; já versionada → 200 reused
+POST  /data/case/:id/docx                    → .docx do estado atual (a edição, se existir)
 ```
 
+`contentHash` é o sha256 do `html` exatamente como foi gravado (o servidor não
+normaliza): num save que deu timeout, compare com o hash do que você enviou
+pela listagem, sem baixar o documento. `baseUpdatedAt` no `POST …/versions`
+amarra o checkpoint à revisão que você viu: a versão nunca sai com o seu nome
+e o texto que outra pessoa salvou depois, e repetir a chamada não duplica.
+
 ```tsx
 // abrir
 const doc = await api.get(`/case/${caseId}/html`)
 <MinutaEditor key={caseId} html={doc.html} chrome={doc.chrome ?? undefined} margins={doc.margins ?? undefined} onChange={setHtml} />
 
-// salvar (debounce do seu lado)
-await api.patch(`/case/${caseId}/editions/${editionId}`, { html })
+// salvar (debounce do seu lado): baseUpdatedAt = o updatedAt da última resposta
+const saved = await api.patch(`/case/${caseId}/editions/${editionId}`, { html, baseUpdatedAt })
+baseUpdatedAt = saved.updatedAt
 
 // baixar — fiel ao preview, gerado no browser
 const blob = await editor.current!.exportDocx()
 ```
 
-Mande `x-user-email` / `x-user-name` nas chamadas de edição para a autoria
-ficar registrada.
+Mande `x-user-email` / `x-user-name` em toda chamada feita em nome de alguém:
+nas rotas de edição viram `createdBy` (criação), `updatedBy` (último save de
+conteúdo), `createdBy` de cada versão e `deletedBy` (descarte); no
+`PATCH /data/case/:id` viram `updatedByEmail`/`updatedByName` do case. Sem os
+headers a autoria fica `null` — nunca "a integração".
 
 ## Formulário ↔ documento
 
@@ -109,8 +125,9 @@ e o editor trata a marca como nó atômico. Isso dá as duas direções sem casa
 texto (que erra quando o valor coincide com algo que já existia no template):
 
 ```tsx
-// documento → formulário: clicou no trecho, foca o campo
-<MinutaEditor ref={editor} html={html} onVariableClick={v => focusField(v.variableId)} />
+// documento → formulário: clicou no trecho, foca o campo. `kind` diz o que foi
+// clicado: 'text' (chip), 'image' (<img> marcada) ou 'missingImage' (aviso)
+<MinutaEditor ref={editor} html={html} onVariableClick={v => focusField(v.variableId, v.kind)} />
 
 // formulário → documento: focou o campo, rola até o trecho
 editor.current!.scrollToVariable('nome_cliente')
@@ -135,17 +152,23 @@ edição criada a partir de HTML já resolvido (sem marcas) a ponte não existe,
 | `<for item="c" in="contratos"> <variable name="c.numero">` | um chip por linha, com `data-variable-index` | `contratos[0].numero`, `contratos[1].numero`… |
 | `<img variable="img_doc">` com valor | `<img data-variable-id data-parent-block-id>` | `img_doc` |
 | `<img variable="img_doc">` sem valor | aviso `missing-image-warning` (nó `missingImage` no editor) | `img_doc` |
+| `<variable name="valor">` sem valor | aviso vermelho `<span data-variable-id data-parent-block-id data-invalid-variable>` | `valor` |
 | cada bloco do template | `<div data-minuta-block data-block-id data-block-title>` | `data-block-id` = id do bloco no `templateSpec` |
 
-Variável de texto **sem valor** sai como aviso (`data-invalid-variable`), não
-como chip, e não entra em `markedVariables`. Booleans não viram marca: eles
-decidem se um trecho ou bloco é emitido; a regra fica em `displayCondition` e
-nos `<if condition>` do template (podem envolver várias variáveis).
+O aviso de texto sem valor é uma marca como as outras: entra em
+`markedVariables`, dispara `onVariableClick` (`kind: 'text'`) e
+`setVariableValue` o converte em chip comum ao receber valor. Booleans não
+viram marca: eles decidem se um trecho ou bloco é emitido; a regra fica em
+`displayCondition` e nos `<if condition>` do template (podem envolver várias
+variáveis).
 
 ```tsx
 // array: uma linha de cada vez
 editor.current!.setVariableValue('contratos[1].numero', '375586874')
 
+// texto sem valor: o aviso vermelho vira chip
+editor.current!.setVariableValue('valor', 'R$ 1.000,00')
+
 // imagem: troca a existente, ou transforma o aviso de "faltando" em imagem
 editor.current!.setVariableImage('img_doc', urlAssinada)        // → nº de ocorrências
 editor.current!.scrollToVariable('img_faltando')                 // acha o aviso também
@@ -155,11 +178,39 @@ editor.current!.scrollToVariable('img_faltando')                 // acha o aviso
 ```
 
 Sobre o fluxo de "enviar variáveis de volta": com uma edição viva o documento
-**é** a edição — o `PATCH` de variáveis no case não re-renderiza a peça (senão
-apagaria o texto do advogado). Ou o formulário trava quando a lapidação começa
-(o modelo do defesa.ai), ou você mantém os dois vivos com `setVariableValue` +
+**é** a edição — o `PATCH /data/case/:id` de variáveis não re-renderiza a peça
+(senão apagaria o texto do advogado). A API aceita a mudança e devolve
+`activeEdition` (`{ id, name, updatedAt }` da edição que ficou como estava, ou
+`null`) para o app decidir: ou o formulário trava quando a lapidação começa (o
+modelo do defesa.ai), ou você mantém os dois vivos com `setVariableValue` +
 salva a edição. Decisão de UX do seu app; as duas funcionam.
 
+### Imagens inseridas pelo advogado
+
+`uploadImage` devolve `{ src, vaultSrc }`: o editor grava a tag com o `src`
+(presignado, expira) e `data-vault-src` (a `vault://`, durável). Persista o
+`getHTML()` como está: o `POST /data/case/:id/docx` usa o `data-vault-src` e
+resolve `vault://` sozinho. Ao reabrir uma edição salva, renove os links antes
+de mostrar:
+
+```tsx
+// resolver: POST /data/vault/download-url { vaultUrl } → { downloadUrl } (pelo seu backend)
+await editor.current!.refreshVaultImages(vaultUrl => api.post('/vault/download-url', { vaultUrl }).then(r => r.downloadUrl))
+```
+
+Renova tanto `data-vault-src` quanto imagens salvas só com `src="vault://…"`
+(que ganham o `data-vault-src`), mantendo a referência durável. Não entra no
+undo nem dispara `onChange`: chame `getHTML()` depois se guarda uma cópia. O
+`exportDocx()` do browser baixa pelo `src`, então renove antes de exportar.
+
+Se o upload falhar (ou `uploadImage` devolver `null`), o padrão é embutir a
+imagem em base64. Um app cujo documento canônico depende de `vault://` não
+quer isso: `imageFallback="none"` não insere nada e `onImageUploadError` recebe
+o erro e o arquivo para você mostrar e deixar tentar de novo.
+
+`setVariableImage(id, src, vaultSrc)` grava o `data-vault-src` junto — use a
+forma de três argumentos para a imagem sobreviver à expiração do `src`.
+
 ## Next.js (App Router)
 
 O entry publicado carrega `'use client'`: dá para importar o componente direto

package/dist/index.d.mts

@@ -32,6 +32,9 @@ interface MinutaEditorProps {
     chrome?: Partial<MinutaChromeText>;
     variables?: MinutaVariableCatalog;
     uploadImage?: MinutaEditorOptions['uploadImage'];
+    /** `'dataUri'` (default) embute em base64 quando o upload falha; `'none'` não insere e avisa por `onImageUploadError` */
+    imageFallback?: MinutaEditorOptions['imageFallback'];
+    onImageUploadError?: MinutaEditorOptions['onImageUploadError'];
     /** barra de formatação do pacote (default: true). `false` = monte a sua sobre `ref.tiptap` */
     toolbar?: boolean;
     showBlockOrigin?: boolean;

package/dist/index.d.ts

@@ -32,6 +32,9 @@ interface MinutaEditorProps {
     chrome?: Partial<MinutaChromeText>;
     variables?: MinutaVariableCatalog;
     uploadImage?: MinutaEditorOptions['uploadImage'];
+    /** `'dataUri'` (default) embute em base64 quando o upload falha; `'none'` não insere e avisa por `onImageUploadError` */
+    imageFallback?: MinutaEditorOptions['imageFallback'];
+    onImageUploadError?: MinutaEditorOptions['onImageUploadError'];
     /** barra de formatação do pacote (default: true). `false` = monte a sua sobre `ref.tiptap` */
     toolbar?: boolean;
     showBlockOrigin?: boolean;

package/dist/index.mjs

@@ -21,6 +21,8 @@ const MinutaEditor = forwardRef((props, ref) => {
       variables: props.variables,
       // lido na hora do upload, não no mount: o host pode trocar a função
       uploadImage: (file) => callbacks.current.uploadImage ? callbacks.current.uploadImage(file) : Promise.resolve(null),
+      imageFallback: props.imageFallback,
+      onImageUploadError: (error, file) => callbacks.current.onImageUploadError?.(error, file),
       toolbar: props.toolbar,
       showBlockOrigin: props.showBlockOrigin,
       blockClickWhileEditing: props.blockClickWhileEditing,
@@ -64,6 +66,9 @@ const MinutaEditor = forwardRef((props, ref) => {
   useEffect(() => {
     instance.current?.setBlockClickWhileEditing(props.blockClickWhileEditing === true);
   }, [props.blockClickWhileEditing]);
+  useEffect(() => {
+    instance.current?.setImageFallback(props.imageFallback ?? "dataUri");
+  }, [props.imageFallback]);
   useImperativeHandle(ref, () => instance.current);
   return createElement("div", {
     ref: host,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/minuta-react",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Componente React do editor de minuta do defesa.ai — casca fina sobre @meistrari/minuta-editor",
   "repository": {
     "type": "git",