@meistrari/minuta-react 1.0.0 → 1.2.0

package/README.md

@@ -36,13 +36,16 @@ um `Blob` de `.docx`. Buscar o documento, persistir a edição e baixar o arquiv
 | `variables` | — | catálogo `{ key, label, description?, group? }[]` → liga o modo template |
 | `uploadImage` | — | `(file) => Promise<{ src, vaultSrc } \| null>` |
 | `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 |
 | `onTransaction` | — | qualquer transação, inclusive só de seleção — para toolbar própria |
 | `onReady`, `onEditChrome`, `onBlockClick`, `onError` | — | |
 
 O `ref` entrega a instância do editor: `getHTML()`, `exportDocx()` (→ `Blob`),
 `usedVariables()`, `setEditable()`, `setChrome()`, `tiptap` (a instância do
-Tiptap — escotilha de fuga), `root`/`container`/`sheet` (os elementos).
+Tiptap — escotilha de fuga), `root`/`container`/`sheet` (os elementos) — e a
+ponte formulário ↔ documento: `scrollToVariable()`, `setVariableValue()`,
+`setVariableImage()`, `variablesInDocument()` (abaixo).
 
 ### Por que o `html` é lido uma vez
 
@@ -77,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
@@ -88,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
 
@@ -106,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')
@@ -123,12 +133,63 @@ edição criada a partir de HTML já resolvido (sem marcas) a ponte não existe,
 é melhor saber antes de montar a tela do que descobrir com
 `variablesInDocument()` vazio.
 
+### O que é marcado, e com que id
+
+| no template | no HTML | id da marca |
+|---|---|---|
+| `<variable name="comarca">` | `<span data-variable-id data-parent-block-id>` (chip) | `comarca` |
+| variável `compute` | idem — o valor é calculado antes do render | o id da compute |
+| `<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` |
+
+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
+
+// bloco: com blockClickWhileEditing o clique em edição também avisa
+<MinutaEditor blockClickWhileEditing onBlockClick={id => openChecklistBlock(id)} … />
+```
+
 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/dist/index.d.mts

@@ -35,6 +35,8 @@ interface MinutaEditorProps {
     /** barra de formatação do pacote (default: true). `false` = monte a sua sobre `ref.tiptap` */
     toolbar?: boolean;
     showBlockOrigin?: boolean;
+    /** dispara `onBlockClick` também em edição (padrão: só em leitura) */
+    blockClickWhileEditing?: boolean;
     onReady?: MinutaEditorOptions['onReady'];
     /** o documento mudou por edição — recebe o HTML atual */
     onChange?: (html: string) => void;

package/dist/index.d.ts

@@ -35,6 +35,8 @@ interface MinutaEditorProps {
     /** barra de formatação do pacote (default: true). `false` = monte a sua sobre `ref.tiptap` */
     toolbar?: boolean;
     showBlockOrigin?: boolean;
+    /** dispara `onBlockClick` também em edição (padrão: só em leitura) */
+    blockClickWhileEditing?: boolean;
     onReady?: MinutaEditorOptions['onReady'];
     /** o documento mudou por edição — recebe o HTML atual */
     onChange?: (html: string) => void;

package/dist/index.mjs

@@ -23,6 +23,7 @@ const MinutaEditor = forwardRef((props, ref) => {
       uploadImage: (file) => callbacks.current.uploadImage ? callbacks.current.uploadImage(file) : Promise.resolve(null),
       toolbar: props.toolbar,
       showBlockOrigin: props.showBlockOrigin,
+      blockClickWhileEditing: props.blockClickWhileEditing,
       onReady: (tiptap) => callbacks.current.onReady?.(tiptap),
       onChange: () => callbacks.current.onChange?.(editor.getHTML()),
       onTransaction: () => callbacks.current.onTransaction?.(),
@@ -60,6 +61,9 @@ const MinutaEditor = forwardRef((props, ref) => {
   useEffect(() => {
     instance.current?.setShowBlockOrigin(props.showBlockOrigin !== false);
   }, [props.showBlockOrigin]);
+  useEffect(() => {
+    instance.current?.setBlockClickWhileEditing(props.blockClickWhileEditing === true);
+  }, [props.blockClickWhileEditing]);
   useImperativeHandle(ref, () => instance.current);
   return createElement("div", {
     ref: host,

package/package.json

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