@meistrari/minuta-react 1.1.0 → 1.2.0

package/README.md

@@ -80,10 +80,12 @@ 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, … }
+PATCH /data/case/:id/editions/:id            → salva → { updatedAt, updatedBy, … }
+      { html, baseUpdatedAt }                  400 sem o token; 409 se outro salvou antes
+POST  /data/case/:id/editions/:id/versions   → marco no histórico (o PATCH NÃO cria versão)
+POST  /data/case/:id/docx                    → .docx do estado atual (a edição, se existir)
 ```
 
 ```tsx
@@ -91,15 +93,19 @@ POST  /data/case/:id/docx                         → .docx do estado atual (a e
 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 +115,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 +142,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 +168,28 @@ 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). 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))
+```
+
+Não entra no undo nem dispara `onChange`. O `exportDocx()` do browser baixa
+pelo `src`, então renove antes de exportar também; o `POST /data/case/:id/docx`
+resolve `vault://` sozinho.
+
 ## Next.js (App Router)
 
 O entry publicado carrega `'use client'`: dá para importar o componente direto

package/package.json

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